@seanyao/roll 2026.513.1 → 2026.514.1

package/CHANGELOG.md

@@ -1,21 +1,30 @@
 # Changelog
 
+## Unreleased
+- **Fixed**: dashboard 不再在已发版后还显示 "✓ Release ready"——只有 tag 之后存在非 docs/chore 的可发版提交时才亮，光是文档改写不会再让它误报
+- **Fixed**: dashboard 上 "📋 N PROPOSAL" 的动作提示改成 `see: PROPOSALS.md`，原先指向的 `roll backlog` 只看 BACKLOG.md，点过去看不到 PROPOSAL，逻辑断头
+- **Added**: changelog 生成时自动挡掉技术黑话
+- **Added**: 写 changelog 时会先参考最近几次发布的风格
+- **Added**: 故事跑完自动开 PR + auto-merge，CI 绿就合
+- **Added**: 完成的故事不再直接 push main，留下 PR 作为审计入口
+- **Added**: AI 代码评审可以批准 / 打回 PR — 配合 CI 形成合并双门；紧急 hotfix 在 PR body 加 `[skip-ai-review]` 即可绕开
+- **Added**: changelog 现在自审挡黑话
+
 ## v2026.513.1
-- **Added**: loop worktree 隔离 Phase 2 — `_write_loop_runner_script` 现在让每轮 cron 在独立的 `loop/cycle-<ts>-<pid>` worktree 里跑 claude，结束后 ff-merge 回 main + 自动清理；失败保留 worktree + 写 ALERT。loop 不再吞 main 的 WIP，多轮之间也完全隔离。claude 仍保留 story selection 权（SKILL.md 不变）
-- **Added**: loop worktree 隔离 Phase 1 — `bin/roll` 新增 7 个 `_worktree_*` helpers（path / create 幂等 / cleanup / fetch lenient / submodule init / merge_back ff-only / alert），覆盖 loop 在独立 worktree 跑 story 的完整生命周期；零行 runner.sh 改动，loop 自己也能跑；US-AUTO-037 (manual-only) 之后把这些 helpers 接入 `_write_loop_runner_script`
-- **Added**: loop 依赖闸门 — BACKLOG 行末尾的 `` `depends-on:US-X,US-Y` `` 和 `` `manual-only:true` `` 标签从此具有强制力；loop 选 story 前先用 `_loop_check_depends_on` / `_loop_is_manual_only` 两个 helper 过一遍，未满足依赖或带 manual-only 标的 story 直接跳过并写 `skipped` runs.jsonl 记录，不再需要靠人盯标签
-- **Fixed**: loop 并发保护补丁 — 2026-05-13 14:37 实测同 runner 下出现并发 claude 会话同时改 state.yaml / BACKLOG / git；inner script 现新增二级 LOCK（PID + start-ts 4h 双校验），守住 claude 调用现场，外层 LOCK 即使被旁路也兜底
-- **Changed**: CI 拆 unit / integration 双 job 并行 — `tests/run.sh` 接受可选目录参数；`.github/workflows/ci.yml` 用 `strategy.matrix` 把 509 unit + 70 integration 用例分到两个 runner 并行跑（REFACTOR-009 Phase 1B）；Phase 2 测试瘦身拆到 REFACTOR-010
-- **Changed**: `roll`（无参）dashboard 重设计 — 自治优先六块布局：① Identity（项目名 + 版本 + agent + git 状态）② AI 自治主视觉（Loop / Dream / Peer 三层 + 四道防线，框线高亮）③ Pipeline 全景（Idea/Backlog/Build/Verify/Release 五段计数）④ Current Focus · DoD（in-progress story 的 [AC] [CI] 信号，其余 4 项标注待接入）⑤ Human × AI 介入区（ALERT/PROPOSAL/Release ready，空时显示"AI 自驱中"）⑥ Schedules & Last Brief。把"AI 自动跑什么"放第一眼，不再埋在 `roll loop status` 子命令里
-- **Changed**: CI 测试运行器 (`tests/run.sh`) 动态检测核数（`nproc`/`sysctl`）替换硬编码 `--jobs 4`，可用 `ROLL_TEST_JOBS` 覆盖；bats-core submodule 缺失时给出清晰报错
-- **Changed**: GitHub Actions CI 跳过 docs-only PR（`paths-ignore: **.md, docs/**`），文档改动不再触发全套 bats
-- **Fixed**: `roll peer` 在 REFINE/OBJECT 退出路径上的 "resolution: unbound variable" 风险 — cmd_peer 显式初始化 `local resolution=""`，并补齐 AGREE/REFINE/OBJECT/ESCALATE/UNKNOWN 五条退出路径的回归测试
-- **Fixed**: `roll update` 后 `roll loop status` 误报 off — `_install_launchd_plists` reload 路径改用 `launchctl bootout` + `bootstrap`（不动 overrides db），消除 macOS Sonoma+ 上 no-`-w` unload/load 把 label `enabled` 标记吞掉的副作用；不再需要手动 `roll loop on` 恢复
+- **Added**: loop 现在每轮跑在独立的 worktree 里，结束自动合回 main 并清理；跑挂时保留现场目录方便排查 — 再也不会吞掉 main 上你正在改的代码
+- **Added**: BACKLOG 上的 `depends-on:` 和 `manual-only:true` 标签从此有强制力，loop 选 story 前会过一遍，依赖没满足或标 manual-only 的直接跳过，不用人盯
+- **Fixed**: loop 多了一道并发保护 — 偶发的同一个 runner 下两个 claude 同时改状态的情况彻底堵住
+- **Changed**: CI 把 unit 和 integration 测试拆到两个 runner 并行跑，墙钟时间显著下降
+- **Changed**: `roll`（不带参数）的 dashboard 重新设计 — AI 在自动跑什么放第一眼，自治三层 + 四道防线 + Pipeline 全景 + 当前焦点 + 介入区一屏看完，不用再去 `roll loop status` 子命令翻
+- **Changed**: 测试运行器自动按机器核数并行，不再写死 4 个 job
+- **Changed**: 纯文档改动不再触发 CI 跑全套测试，文档 PR 合并节奏更快
+- **Fixed**: `roll peer` 在 REFINE / OBJECT 收尾时偶发的 "unbound variable" 崩溃
+- **Fixed**: `roll update` 后 `roll loop status` 不再误报 off，不用手动 `roll loop on` 恢复
 
 ## v2026.512.8
-- **Added**: `$roll-doc` — legacy 项目文档自动化技能：四阶段扫描（索引 + 缺口分析 + 草稿补全 + 报告），支持 `--dry-run` / `--force`，适用任何项目
-- **Added**: `roll-.dream` Scan 6 — 文档新鲜度检测（滞后文档 / 未记录 ENV 变量 / 架构文档缺失），依赖 roll-doc，发现写入 REFACTOR 条目
-- **Fixed**: loop CI gate 在 SSH config 改写 github.com 为 IP 的环境下失灵 — `gh` 自动识别失败被静默吞掉，loop 把 "gh 出错" 误判为 "gh 未装"，在 CI 红的情况下继续把 story 标 ✅ Done；现从 git remote 推导 `owner/repo` 强制传 `-R`，gh 调用失败 = ALERT，loop 起跑前先验 HEAD CI 红绿，红则拒绝 build
+- **Added**: `$roll-doc` — 扫描任意项目的文档现状，找出缺口并生成草稿，支持 `--dry-run`
+- **Added**: `roll-.dream` Scan 6 — 每晚检测文档是否跟代码脱节，发现问题自动写进重构待办
+- **Fixed**: 某些 SSH 配置下 loop 把"CI 查询失败"误判为"CI 工具未安装"，导致测试没过就标任务完成
 
 ## v2026.512.7
 - **Added**: `roll alert` — 查看、确认、清除 loop 告警，不用再去翻 loop status
@@ -23,10 +32,10 @@
 - **Added**: `roll ci [--wait]` — 查看当前提交的 CI 状态，或等待 CI 跑完再继续
 - **Fixed**: loop 现在会等 CI 通过后才标记故事完成，CI 失败则保持进行中并发出提醒
 - **Fixed**: changelog 更新不再产生独立 commit，并入故事完成提交，git log 更干净
-- **Added**: `docs/domain/` — Roll 架构的 DDD 领域模型文档（5 个 Bounded Context + 自治操作 Aggregate 设计）
+- **Added**: `docs/domain/` — Roll 架构领域模型文档
 - **Fixed**: `roll loop runs` 不再报"当前项目尚无运行记录"，历史记录正常显示
-- **Added**: 文档目录重组 — methodology、skill 选择指南、loop 验证记录迁移至 `docs/guide/` 和 `docs/practices/`，根目录不再有散落文件
-- **Added**: README 大幅精简并新增文档导航索引 — 首页更清晰，所有指南一表可查
+- **Added**: 文档目录重组 — 散落文档统一迁移至 `docs/guide/` 和 `docs/practices/`
+- **Added**: README 精简，新增文档导航索引
 - **Added**: dream 每晚自动检测文档缺口，brief 新增文档覆盖率数字
 
 ## v2026.512.6
@@ -91,8 +100,8 @@
 - **Fixed**: release.yml 加 fetch-depth: 0，确保历史 tag 在 workflow 中可见
 
 ## v2026.510.8
-- **Fixed**: release.sh 自洽 — 内联 agent 检测和 changelog 同步，发版流程不依赖外部调用
-- **Fixed**: roll release 命令重构 — 改为独立调用 roll-release skill，与 scripts/release.sh 解耦
+- **Fixed**: release.sh 自洽 — 发版流程不依赖外部调用
+- **Fixed**: `roll release` 改为独立调用 roll-release skill，与 release.sh 解耦
 - **Fixed**: GitHub Release workflow 加 fetch-depth: 0，确保历史 tag 可见
 
 ## v2026.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.513.1"
+VERSION="2026.514.1"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -609,6 +609,36 @@ cmd_setup() {
 
   echo ""
   info "Next: run ${BOLD}roll init${NC} inside a project to initialize it.  下一步：在项目目录运行 roll init"
+
+  echo ""
+  _print_pr_pipeline_hint
+}
+
+# ─── PR pipeline hint ────────────────────────────────────────────────────────
+# US-AUTO-035: print the one-time branch-protection command that flips repo
+# from path A (CI gate only) to path C (CI + AI review double gate). Reading
+# this hint is opt-in; the command is destructive (changes branch protection)
+# so it is never run automatically.
+_print_pr_pipeline_hint() {
+  cat <<'HINT'
+
+  Optional — enable AI review as a hard merge gate (path C).
+  可选 —— 启用 AI 评审作为合并双门（路径 C）。
+
+  Run once per repo (requires admin token), then claude-code-review.yml
+  approvals become a required merge gate alongside CI:
+  每个仓库执行一次（需要管理员 token），之后 claude-code-review.yml 的
+  approve 将与 CI 一起成为合并必经的双门：
+
+      gh api -X PATCH repos/<owner>/<repo>/branches/main/protection \
+        -f required_pull_request_reviews.required_approving_review_count=1
+
+  Escape hatch: add [skip-ai-review] to a PR body, or include
+  SKIP_AI_REVIEW in any commit message, to bypass AI review for that PR.
+  紧急通道：在 PR body 加 [skip-ai-review]，或在任一 commit message
+  里包含 SKIP_AI_REVIEW，可对该 PR 绕过 AI 评审。
+
+HINT
 }
 
 # ═══════════════════════════════════════════════════════════════════════════════
@@ -2118,15 +2148,31 @@ for _attempt in 1 2 3; do
   fi
 done
 
-# Post-claude: merge back if we used an isolated worktree.
+# Post-claude: publish cycle branch. Doc-only changes (BACKLOG/docs) merge
+# immediately via --admin; code changes use auto-merge (CI gate required).
+# When \`gh\` is unavailable, fall back to the legacy ff-merge path.
 if [ "\$_USE_WORKTREE" = "1" ]; then
   if [ "\$_exit" -eq 0 ]; then
-    if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+    if ( cd "\$WT" && _loop_is_doc_only_change ); then
+      ( cd "\$WT" && _loop_publish_doc_pr "\$BRANCH" "doc: loop cycle \${CYCLE_ID}" )
+    else
+      ( cd "\$WT" && _loop_publish_pr "\$BRANCH" "loop cycle \${CYCLE_ID}" )
+    fi
+    _publish_status=\$?
+    if [ "\$_publish_status" -eq 0 ]; then
       _worktree_cleanup "\$WT" "\$BRANCH"
-      echo "[loop] cycle \${CYCLE_ID}: merged and cleaned up"
+      echo "[loop] cycle \${CYCLE_ID}: published; worktree cleaned"
+    elif [ "\$_publish_status" -eq 2 ]; then
+      if ( cd "${project_path}" && _worktree_merge_back "\$BRANCH" ); then
+        _worktree_cleanup "\$WT" "\$BRANCH"
+        echo "[loop] cycle \${CYCLE_ID}: gh unavailable; merged via ff and cleaned up"
+      else
+        _worktree_alert "cycle \${CYCLE_ID}: gh unavailable AND merge_back failed; worktree preserved at \$WT"
+        echo "[loop] cycle \${CYCLE_ID}: gh+merge_back both failed; worktree preserved at \$WT"
+      fi
     else
-      _worktree_alert "cycle \${CYCLE_ID}: merge_back failed; worktree preserved at \$WT (branch \$BRANCH)"
-      echo "[loop] cycle \${CYCLE_ID}: merge_back failed; worktree preserved at \$WT"
+      _worktree_alert "cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT (branch \$BRANCH)"
+      echo "[loop] cycle \${CYCLE_ID}: PR publish failed; worktree preserved at \$WT"
     fi
   else
     _worktree_alert "cycle \${CYCLE_ID}: claude exited \$_exit; worktree preserved at \$WT (branch \$BRANCH)"
@@ -3055,6 +3101,172 @@ _loop_is_manual_only() {
   echo "$row" | grep -qE 'manual-only:true'
 }
 
+# US-CL-004: changelog 风格守门 Phase 1 — mechanical linter.
+#
+# _changelog_lint_bullet <bullet-text>
+#   Stdout: one violation tag per line; empty = bullet passes.
+#   Exit:   0 always (callers read the output stream, not the exit code).
+#
+# Violation tags:
+#   backtick-identifier  `…` contains `_` or `()`  (e.g. `_foo`, `bar()`)
+#   file-suffix          `.md`/`.sh`/`.yml`/`.ts`/`.bats` outside backticks
+#   internal-word        Phase N / Step N / Helper / Schema / Fixture / Refactor
+#   over-length          > 50 visible chars (UTF-8 codepoints; 中文按字符计)
+#   path-fragment        docs/ / bin/ / tests/ / scripts/ outside backticks
+#
+# Backticks are treated as the "user-quoted" zone — content there is assumed
+# to be a real user command (e.g. `roll edit notes.md`) and is excluded from
+# the file-suffix / path-fragment checks.
+_changelog_lint_bullet() {
+  local bullet="$1"
+  local stripped
+  stripped=$(printf '%s' "$bullet" | sed -E 's/`[^`]*`//g')
+
+  if printf '%s' "$bullet" | grep -qE '`[^`]*(_|\(\))[^`]*`'; then
+    echo "backtick-identifier"
+  fi
+  if printf '%s' "$stripped" | grep -qE '\.(md|sh|yml|ts|bats)([^A-Za-z0-9]|$)'; then
+    echo "file-suffix"
+  fi
+  if printf '%s' "$bullet" | grep -qE '(Phase|Step)[[:space:]]+[0-9]+|Helper|Schema|Fixture|Refactor'; then
+    echo "internal-word"
+  fi
+  local len
+  len=$(printf '%s' "$bullet" | LC_ALL=C.UTF-8 wc -m | tr -d ' ')
+  if [ "${len:-0}" -gt 50 ]; then
+    echo "over-length"
+  fi
+  if printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+    echo "path-fragment"
+  fi
+  return 0
+}
+
+# US-CL-004: changelog few-shot style anchors — extract bullets from the
+# most recent 3 published `## v...` sections of CHANGELOG.md (skipping
+# `## Unreleased`). Cap at ~1500 chars so the agent's context stays lean.
+#
+# _changelog_style_anchors [changelog-path]
+#   Stdout: concatenated bullet lines from the last 3 released versions.
+#   Exit:   0 (empty output when no CHANGELOG.md or no released sections).
+_changelog_style_anchors() {
+  local changelog="${1:-CHANGELOG.md}"
+  [ -f "$changelog" ] || return 0
+  awk '
+    /^## v/ { ver++; if (ver > 3) exit; printing = 1; next }
+    /^## /  { printing = 0 }
+    printing && /^- / { print }
+  ' "$changelog" | head -c 1500
+}
+
+# US-CL-005: changelog 风格守门 Phase 2 — self-audit gate.
+#
+# _changelog_audit_bullet <bullet>
+#   Stricter than _changelog_lint_bullet: 5 boolean rules, 30-char cap.
+#   Stdout: one failed-rule tag per line; empty = bullet passes.
+#   Exit:   0 always.
+#
+# Rules:
+#   over-length-30   visible chars > 30 AND no backtick (user-cmd escape hatch)
+#   internal-id      backtick content contains `_` or `()`
+#   path-or-suffix   .md/.sh/.yml/.ts/.bats or docs/bin/tests/scripts/ outside backticks
+#   phase-step       `Phase N` / `Step N` workflow vocabulary
+#   bad-shape        no `—` (em dash) AND no `不再` AND no `现在` keyword
+_changelog_audit_bullet() {
+  local bullet="$1"
+  local stripped
+  stripped=$(printf '%s' "$bullet" | sed -E 's/`[^`]*`//g')
+
+  # Rule 1: length cap 30 (user-command in backticks bypasses this rule).
+  if ! printf '%s' "$bullet" | grep -q '`'; then
+    local len
+    len=$(LC_ALL=en_US.UTF-8 printf '%s' "$bullet" | LC_ALL=en_US.UTF-8 wc -m | tr -d ' ')
+    if [ "${len:-0}" -gt 30 ]; then
+      echo "over-length-30"
+    fi
+  fi
+
+  # Rule 2: internal identifier inside backticks.
+  if printf '%s' "$bullet" | grep -qE '`[^`]*(_|\(\))[^`]*`'; then
+    echo "internal-id"
+  fi
+
+  # Rule 3: file suffix / path fragment outside backticks.
+  if printf '%s' "$stripped" | grep -qE '\.(md|sh|yml|ts|bats)([^A-Za-z0-9]|$)' \
+    || printf '%s' "$stripped" | grep -qE '(^|[^A-Za-z0-9_])(docs|bin|tests|scripts)/'; then
+    echo "path-or-suffix"
+  fi
+
+  # Rule 4: workflow vocabulary.
+  if printf '%s' "$bullet" | grep -qE '(Phase|Step)[[:space:]]+[0-9]+'; then
+    echo "phase-step"
+  fi
+
+  # Rule 5: required shape — em dash, 不再, or 现在.
+  if ! printf '%s' "$bullet" | grep -qE '—|不再|现在'; then
+    echo "bad-shape"
+  fi
+
+  return 0
+}
+
+# _changelog_audit_log <verdict> <round> <bullet> [<reason>...]
+#   Append a JSONL record to the audit log. Path overridable via
+#   ROLL_CHANGELOG_AUDIT_LOG (tests use this to stay out of $HOME).
+_changelog_audit_log() {
+  local verdict="$1" round="$2" bullet="$3"
+  shift 3
+  local log="${ROLL_CHANGELOG_AUDIT_LOG:-${_SHARED_ROOT}/loop/changelog-audit.jsonl}"
+  mkdir -p "$(dirname "$log")"
+  local ts; ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  local reasons_json='[]'
+  if [ "$#" -gt 0 ]; then
+    reasons_json=$(printf '%s\n' "$@" | jq -R . | jq -sc .)
+  fi
+  jq -nc \
+    --arg ts "$ts" \
+    --arg verdict "$verdict" \
+    --argjson round "$round" \
+    --arg bullet "$bullet" \
+    --argjson reasons "$reasons_json" \
+    '{ts:$ts, verdict:$verdict, round:$round, bullet:$bullet, reasons:$reasons}' \
+    >> "$log"
+}
+
+# _changelog_audit_gate <round1> [<round2> <round3>]
+#   Run up to 3 candidate bullets through _changelog_audit_bullet.
+#   First clean candidate wins: print bullet to stdout, exit 0.
+#   All 3 failed: print ⚠️-prefixed last candidate, append ALERT, exit 1.
+#   Each round writes a _changelog_audit_log record.
+_changelog_audit_gate() {
+  local i=0 last=""
+  for candidate in "$@"; do
+    i=$((i + 1))
+    last="$candidate"
+    local viols
+    # shellcheck disable=SC2207
+    viols=( $(_changelog_audit_bullet "$candidate") )
+    if [ "${#viols[@]}" -eq 0 ]; then
+      _changelog_audit_log pass "$i" "$candidate"
+      printf '%s\n' "$candidate"
+      return 0
+    fi
+    _changelog_audit_log fail "$i" "$candidate" "${viols[@]}"
+    [ "$i" -ge 3 ] && break
+  done
+  # All 3 rounds failed (or fewer if caller passed < 3).
+  mkdir -p "$(dirname "$_LOOP_ALERT")" 2>/dev/null
+  {
+    echo ""
+    echo "# ALERT — changelog audit failed after $i rounds"
+    echo "**Time**: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    echo "**Bullet**: $last"
+    echo "**Action**: kept under \`## Unreleased\` with ⚠️ prefix; human review recommended."
+  } >> "$_LOOP_ALERT"
+  printf '⚠️ %s\n' "$last"
+  return 1
+}
+
 # US-AUTO-036: worktree helpers (loop-safe pure additions).
 #
 # Phase 1 of worktree isolation — these helpers are NOT yet called by
@@ -3150,6 +3362,107 @@ _worktree_merge_back() {
   return 0
 }
 
+# US-AUTO-033: publish a loop cycle branch as a GitHub PR with auto-merge.
+#
+# _loop_publish_pr <branch> [title]
+#   Caller's cwd: a tree where <branch> exists locally.
+#   Steps:
+#     1. git push origin <branch>
+#     2. gh pr view <branch>  → reuse if a PR is already open
+#     3. gh pr create --base main --head <branch> ...
+#     4. gh pr merge <branch> --auto --squash --delete-branch
+#   Stdout: PR URL (always, even on idempotent reuse).
+#   Exit 0 on success / idempotent reuse; non-zero on push or create failure.
+#   On auto-merge failure: still returns 0 (PR exists; human can take over).
+#   When `gh` is not installed: returns 2 — runner script's fallback path.
+_loop_publish_pr() {
+  local branch="$1"
+  local title="${2:-loop cycle ${branch#loop/}}"
+  if ! command -v gh >/dev/null 2>&1; then
+    _worktree_alert "_loop_publish_pr: gh not installed; cannot publish PR for ${branch}"
+    return 2
+  fi
+  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
+  if [ -z "$slug" ]; then
+    _worktree_alert "_loop_publish_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
+    return 2
+  fi
+  local _push_err
+  _push_err=$(git push origin "$branch" 2>&1) || {
+    _worktree_alert "_loop_publish_pr: push origin ${branch} failed: ${_push_err}"
+    return 1
+  }
+  local pr_url
+  pr_url=$(gh -R "$slug" pr view "$branch" --json url -q .url 2>/dev/null) || pr_url=""
+  if [ -z "$pr_url" ]; then
+    local body
+    body=$(printf 'Auto-opened by roll-loop cycle.\n\n- Branch: %s\n- TCR micro-commits: %s\n\nThis PR will auto-merge once required checks pass.' \
+      "$branch" "$(git rev-list --count origin/main.."$branch" 2>/dev/null || echo '?')")
+    pr_url=$(gh -R "$slug" pr create --base main --head "$branch" \
+      --title "$title" --body "$body" 2>/dev/null) || pr_url=""
+    if [ -z "$pr_url" ]; then
+      _worktree_alert "_loop_publish_pr: gh pr create failed for ${branch}"
+      return 1
+    fi
+  fi
+  gh -R "$slug" pr merge "$branch" --auto --squash --delete-branch >/dev/null 2>&1 \
+    || _worktree_alert "_loop_publish_pr: gh pr merge --auto failed for ${branch} (PR ${pr_url} left open)"
+  echo "$pr_url"
+  return 0
+}
+
+# _loop_is_doc_only_change
+#   Returns 0 if every file changed since origin/main is doc-only
+#   (BACKLOG.md, CHANGELOG.md, PROPOSALS.md, docs/, .claude/).
+#   Returns 1 if any code file changed or there are no changes.
+_loop_is_doc_only_change() {
+  local changed
+  changed=$(git diff --name-only origin/main HEAD 2>/dev/null) || return 1
+  [ -z "$changed" ] && return 1
+  echo "$changed" | grep -qvE '^(BACKLOG\.md|CHANGELOG\.md|PROPOSALS\.md|docs/|\.claude/)' && return 1
+  return 0
+}
+
+# _loop_publish_doc_pr <branch> [title]
+#   Like _loop_publish_pr but merges immediately with --admin (no CI wait).
+#   For doc-only changes where CI is not meaningful.
+_loop_publish_doc_pr() {
+  local branch="$1"
+  local title="${2:-doc update ${branch#loop/}}"
+  if ! command -v gh >/dev/null 2>&1; then
+    _worktree_alert "_loop_publish_doc_pr: gh not installed; cannot publish PR for ${branch}"
+    return 2
+  fi
+  local slug; slug=$(_gh_repo_slug 2>/dev/null) || slug=""
+  if [ -z "$slug" ]; then
+    _worktree_alert "_loop_publish_doc_pr: origin remote is not a github repo; cannot publish PR for ${branch}"
+    return 2
+  fi
+  if ! git push origin "$branch" --quiet 2>/dev/null; then
+    _worktree_alert "_loop_publish_doc_pr: push origin ${branch} failed"
+    return 1
+  fi
+  local pr_url
+  pr_url=$(gh -R "$slug" pr view "$branch" --json url -q .url 2>/dev/null) || pr_url=""
+  if [ -z "$pr_url" ]; then
+    local body
+    body=$(printf 'Doc-only update by roll-loop cycle.\n\n- Branch: %s\n- Files: BACKLOG / docs only\n\nMerging immediately — no CI gate needed for doc-only changes.' "$branch")
+    pr_url=$(gh -R "$slug" pr create --base main --head "$branch" \
+      --title "$title" --body "$body" 2>/dev/null) || pr_url=""
+    if [ -z "$pr_url" ]; then
+      _worktree_alert "_loop_publish_doc_pr: gh pr create failed for ${branch}"
+      return 1
+    fi
+  fi
+  if ! gh -R "$slug" pr merge "$branch" --admin --squash --delete-branch >/dev/null 2>&1; then
+    _worktree_alert "_loop_publish_doc_pr: gh pr merge --admin failed for ${branch} (PR ${pr_url} left open)"
+    echo "$pr_url"
+    return 1
+  fi
+  echo "$pr_url"
+  return 0
+}
+
 _loop_monitor() {
   local interval="${1:-3}"
   local project_path; project_path=$(pwd -P)
@@ -3807,8 +4120,20 @@ _dash_proposal_count() {
   grep '^## PROPOSAL' PROPOSALS.md 2>/dev/null | wc -l | tr -d ' '
 }
 
-# ⑤ Release-ready signal — true if latest brief contains 可发版 or "Release ready".
+# ⑤ Release-ready signal — true iff there are releasable commits since the
+# latest tag AND the latest brief signals 可发版/Release ready. Releasable =
+# any commit since the latest tag whose subject does NOT start with the
+# release-irrelevant prefixes `docs:` or `chore:`. Prevents the flag from
+# sticking on after a release when only docs rewrites land on top of the tag
+# (FIX-033 symptom 2).
 _dash_release_ready() {
+  local latest_tag
+  latest_tag=$(git describe --tags --abbrev=0 2>/dev/null) || return 1
+  local commits_with_code
+  commits_with_code=$(git log "${latest_tag}..HEAD" --pretty=format:%s 2>/dev/null \
+    | grep -cvE '^(docs|chore)(\([^)]*\))?:[[:space:]]' 2>/dev/null \
+    || echo 0)
+  [[ "${commits_with_code:-0}" -gt 0 ]] || return 1
   local latest
   latest=$(ls docs/briefs/*.md 2>/dev/null | sort | tail -1 || true)
   [[ -z "$latest" ]] && return 1
@@ -3988,7 +4313,7 @@ _dashboard() {
     printf "    ${GREEN}✓ AI 自驱中 — 无需介入${NC}\n"
   else
     (( alerts > 0 )) && printf "    ${RED}⚠ %s ALERT${NC}          run: roll alert\n" "$alerts"
-    (( proposals > 0 )) && printf "    ${YELLOW}📋 %s PROPOSAL${NC}      run: roll backlog\n" "$proposals"
+    (( proposals > 0 )) && printf "    ${YELLOW}📋 %s PROPOSAL${NC}      see: PROPOSALS.md\n" "$proposals"
     $release_ready && printf "    ${GREEN}✓ Release ready${NC}    run: roll release\n"
   fi
   echo ""

package/conventions/global/AGENTS.md

@@ -40,6 +40,12 @@
   - Before claiming completion: verify in the target environment mentioned by
     user (e.g., specific CLI tool, remote server, hardware platform).
 - **Workspace**: `BACKLOG.md` index. `docs/features/` for details.
+- **Backlog descriptions** (US, FIX, REFACTOR, IDEA, PROPOSAL): one sentence in plain language.
+  Say what changed and why it matters — not how it works internally.
+  No file paths, function names, parameter lists, or architecture jargon.
+  `depends-on:` and `manual-only:` functional tags are allowed; `Domain:` annotation tags are not.
+  Technical details and AC go in `docs/features/`.
+  A well-written BACKLOG description can be used directly as a CHANGELOG entry.
 - **Done**: Push + CI passes + deployed. Local-only is not done.
 - **Commit message format**:
   - Format: `<type>: <description>` (Git Hook may auto-prepend type prefix)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "2026.513.1",
+  "version": "2026.514.1",
   "description": "Roll — Roll out features with AI agents",
   "scripts": {
     "test": "bash tests/run.sh"

package/skills/roll-.changelog/SKILL.md

@@ -47,6 +47,14 @@ Create mode:
 
 CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清"用户能做什么 / 不再被什么坑"，能不写就不写。
 
+**BACKLOG 描述写好了，CHANGELOG 就是复制 + 过滤，不是重写。**
+如果 BACKLOG 描述已经是人话、一句话、说用户价值，直接用它（去掉 `depends-on:` / `manual-only:` 等功能性标签）。
+只有 BACKLOG 描述包含实现细节或技术黑话时，才需要改写。
+
+**FIX 条目的 filter 规则**：BACKLOG 的 FIX 描述通常是 `<用户症状> — <修复手段>` 结构。
+CHANGELOG 只取破折号前的用户症状，丢弃破折号后的修复手段。
+例：`roll update 后 loop 状态误报 off — reload 改用 bootout+bootstrap` → CHANGELOG 只写 `roll update 后 loop 状态不再误报 off`。
+
 **完全跳过（不写入 CHANGELOG）：**
 - 测试基建（teardown 清理、test isolation、bats helper、CI 时序）
 - prompt / SKILL.md 内部契约（schema 锁定、enum 强制、contract test）
@@ -62,9 +70,9 @@ CHANGELOG 是给**使用者**看的，不是给维护者看的。一句话讲清
 - 看得见的体验变化（布局、文案、速度、可见性）
 - 影响安装、升级、配置的改动
 
-**写法约束：**
+**写法约束（BACKLOG 描述不符合时才介入改写）：**
 
-1. **一行，30 字以内**。超了就是太啰嗦。
+1. **一行**。超了就是太啰嗦。
 2. **不写实现细节**：禁止文件路径、函数名、字段列表、命令参数、配置键名。
 3. **不写数字细节**："3 个服务"、"60+ ghost" 这种内部状态不写。
 4. **说人话**：避免 "幂等"、"trap"、"epoch" 等技术黑话；说"做两次效果一样"、"异常退出也会清理"、"启动时间"。
@@ -133,6 +141,94 @@ assigned.
 Do NOT read `package.json` version, do NOT call `git describe`, do NOT invent
 version numbers like `v2026.511.8`. Just write to `## Unreleased`.
 
+### 5.3 Style Anchors — In-Context Few-Shot
+
+Before drafting bullets, pull the most recent 3 published versions' bullets as
+in-context examples so the agent doesn't write from a blank slate (the blank
+slate is where the technical-jargon habit comes from — the agent is fresh
+from writing function names and just copies them over).
+
+```bash
+_changelog_style_anchors CHANGELOG.md
+```
+
+Output is the concatenated bullet lines from the last 3 `## v...` sections,
+capped at 1500 characters. Use them as a style reference when drafting — pay
+attention to length, voice ("不再被…坑" / "现在 …"), and absence of internal
+names.
+
+### 5.4 Mechanical Lint — Hard Gate
+
+After drafting bullets, run each through the mechanical linter. Any non-empty
+output means the bullet violates at least one blacklist rule and must be
+rewritten.
+
+```bash
+for bullet in "${draft_bullets[@]}"; do
+  violations=$(_changelog_lint_bullet "$bullet")
+  [ -n "$violations" ] && needs_rewrite+=("$bullet :: $violations")
+done
+```
+
+Violation tags emitted by `_changelog_lint_bullet`:
+
+| Tag | Trigger | Why it's noise to users |
+|---|---|---|
+| `backtick-identifier` | `…` contains `_` or `()` | Internal symbol names mean nothing to users |
+| `file-suffix` | `.md/.sh/.yml/.ts/.bats` outside backticks | File paths are maintainer concern |
+| `internal-word` | Phase N / Step N / Helper / Schema / Fixture / Refactor | Workflow/design vocabulary, not user-facing |
+| `over-length` | > 50 visible chars | Too long = probably explaining implementation |
+| `path-fragment` | `docs/` / `bin/` / `tests/` / `scripts/` outside backticks | Source-tree layout is maintainer concern |
+
+**Rewrite loop (max 2 rounds)**:
+1. Show the agent the violation list + original bullet → request rewrite
+2. Re-lint the rewrite
+3. If still violating after 2 rewrites → **keep the bullet but prefix `⚠️ `** so
+   the human reviewer can spot it, AND append a line to
+   `~/.shared/roll/loop/ALERT.md` describing what couldn't be fixed.
+   Never block the whole release on style — let the human take the wheel.
+
+### 5.5 Self-Audit — Stage Gate
+
+The mechanical linter in Step 5.4 catches **blacklist** patterns; the audit
+gate in this step is a **whitelist** of 5 boolean checks that the bullet must
+satisfy before it can be staged. Stricter (30-char cap vs 50) and shape-aware
+(requires the user-facing `—` or `不再`/`现在` sentence pattern).
+
+```bash
+accepted=$(_changelog_audit_gate "$draft1" "$rewrite1" "$rewrite2")
+# Exit 0: stdout = first clean candidate
+# Exit 1: stdout = ⚠️-prefixed last candidate; ALERT was written
+```
+
+5 boolean checks evaluated by `_changelog_audit_bullet`:
+
+| Tag | Trigger |
+|---|---|
+| `over-length-30` | visible chars > 30 (bypassed if bullet has a backticked user command) |
+| `internal-id` | backtick content contains `_` or `()` |
+| `path-or-suffix` | `.md/.sh/.yml/.ts/.bats` or `docs/bin/tests/scripts/` outside backticks |
+| `phase-step` | `Phase N` or `Step N` |
+| `bad-shape` | none of `—`, `不再`, `现在` present |
+
+**3-round retry envelope**:
+1. Round 1 = original draft; if pass → stage immediately
+2. Round 2 = rewrite based on violations from round 1
+3. Round 3 = second rewrite if round 2 also failed
+4. All 3 failed → keep last candidate prefixed with `⚠️ `, append ALERT to
+   `~/.shared/roll/loop/ALERT.md`. **Never block the stage** — let the human
+   reviewer take the wheel. The loop must keep moving.
+
+**Audit log**: every round (pass or fail) appends one JSONL line to
+`~/.shared/roll/loop/changelog-audit.jsonl`:
+
+```json
+{"ts":"2026-05-13T13:50:00Z","verdict":"fail","round":1,"bullet":"...","reasons":["over-length-30","bad-shape"]}
+```
+
+Useful when reviewing whether the agent actually iterated or just rubber-stamped
+its own first draft. Set `ROLL_CHANGELOG_AUDIT_LOG` to redirect (tests only).
+
 ### 5. Generate CHANGELOG.md
 
 **Create mode** (first time, no CHANGELOG.md yet):

package/skills/roll-.dream/SKILL.md

@@ -222,6 +222,8 @@ section of BACKLOG.md:
 | REFACTOR-XXX | {one-line description} — flagged by dream {YYYY-MM-DD} | 📋 Todo |
 ```
 
+`{one-line description}` 写法：一句人话说清楚"什么地方需要改"以及"不改会怎样"。不写函数名、文件路径、技术方案。例：`loop 状态读取逻辑分散在多处，修一处容易遗漏另一处`。
+
 **Threshold**: only flag items where the fix would meaningfully reduce
 complexity or prevent future bugs. Ignore cosmetic issues.
 

package/skills/roll-build/SKILL.md

@@ -284,9 +284,11 @@ When any signal appears, **do not stop — flag it**:
 **REFACTOR entry format in BACKLOG.md:**
 
 ```markdown
-| REFACTOR-001 | Extract payment boundary — leaking into Order module during US-AUTH-003 | 📋 Todo |
+| REFACTOR-001 | {one-line plain-language description} | 📋 Todo |
 ```
 
+描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `docs/features/refactor-log.md`。
+
 **refactor-log.md entry format:**
 
 ```markdown

package/skills/roll-design/SKILL.md

@@ -625,6 +625,8 @@ DOMAIN_DIR="docs/domain/"
 | [US-{DOMAIN}-{N}](docs/features/<feature>.md#us-{domain}-{n}) | {one-line description} | 📋 Todo |
 ```
 
+`{one-line description}` 写法：用户能读懂的一句话，说清楚"能做什么"或"解决了什么麻烦"。不写实现细节、文件路径、函数名。细节和 AC 写在 `docs/features/` 里。写好了可以直接当 CHANGELOG 条目用。
+
 Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 
 **US section in docs/features/\<feature\>.md (full details):**

package/skills/roll-peer/SKILL.md

@@ -180,6 +180,33 @@ If serve mode is available, prefer HTTP transport over direct CLI invocation.
 
 **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.
 
+## Inline Display Mode (Manual Triggers)
+
+When peer review is manually triggered by a human (via `/peer`, "叫上 peer", etc.), the executing agent **must display each round inline in the current conversation**. This applies regardless of which agent is executing — Claude, DeepSeek, Kimi, PI, or any other.
+
+**Per-round display format:**
+
+```
+─── Peer Review · Round N ───────────────────────────────
+→ Sending to [peer]:
+{full message sent to peer}
+
+← [peer] responds:
+{peer's full response, verbatim}
+
+◆ My analysis: {Claude/executing agent's reaction and position for this round}
+─────────────────────────────────────────────────────────
+```
+
+**Rules:**
+- Peer CLI calls must be **synchronous** (do NOT use background/async execution).
+- Show the outgoing message **before** calling the peer, so the user sees what's being asked.
+- Relay the peer's response **verbatim** before adding your own analysis.
+- If a peer call fails or times out, report it immediately inline and either retry or ESCALATE.
+- Negotiation log is still written to `~/.shared/roll/peer/logs/` as usual.
+
+**Why inline, not tmux:** When a human manually triggers peer review inside an agent's interactive session, the conversation IS the visible interface. tmux auto-attach is only relevant for CLI-launched background sessions (`bin/roll peer`), not for skill invocations.
+
 ## Workflow Integration
 
 ### `roll-build` Plan Mode

package/skills/roll-propose/SKILL.md

@@ -74,7 +74,11 @@ Generate between 1 and 3 proposals. For each:
 
 ```
 ## PROPOSAL: {Short title}
+```
+
+`{Short title}` 写法：用户看得懂的一句话，说清楚"加什么"或"解决什么问题"。不用技术术语，不提内部实现。这句话批准后会直接成为 BACKLOG 里的描述。
 
+```
 **Motivation (why):**
 One to two sentences from the user's perspective explaining the pain or opportunity.