@seanyao/roll 2026.509.3 → 2026.510.2

package/bin/roll

@@ -4,7 +4,7 @@ set -euo pipefail
 # Roll — AI Agent Convention Manager
 # Single source of truth for how all AI coding agents behave.
 
-VERSION="2026.509.3"
+VERSION="2026.510.2"
 ROLL_HOME="${ROLL_HOME:-${HOME}/.roll}"
 ROLL_CONFIG="${ROLL_HOME}/config.yaml"
 ROLL_GLOBAL="${ROLL_HOME}/conventions/global"
@@ -592,6 +592,9 @@ cmd_update() {
   info "Re-syncing to AI tools...  正在重新同步到 AI 工具..."
   echo ""
   cmd_setup
+
+  echo ""
+  _show_changelog
 }
 
 # ─── Helper: merge global AGENTS.md into project (no type prompt) ────────────
@@ -1198,6 +1201,7 @@ cmd_status() {
       echo -e "  ${RED}-${NC} $tpl (missing / 缺失)"
     fi
   done
+
 }
 
 check_sync_status() {
@@ -1676,7 +1680,8 @@ main() {
     status)        cmd_status "$@" ;;
     peer)          cmd_peer "$@" ;;
     version|--version|-v) echo "roll v${VERSION}" ;;
-    help|--help|-h|"") usage ;;
+    help|--help|-h) usage ;;
+    "") usage; _show_changelog ;;
     *)
       err "Unknown command: $cmd  未知命令: $cmd"
       echo ""
@@ -1686,6 +1691,27 @@ main() {
   esac
 }
 
+# ─── Show recent changelog entries ────────────────────────────────────────────
+_show_changelog() {
+  local changelog="${ROLL_PKG_DIR}/CHANGELOG.md"
+  [[ -f "$changelog" ]] || return 0
+
+  echo -e "${BOLD}Recent Changes  最近更新:${NC}"
+
+  local count=0 in_section=false
+  while IFS= read -r line; do
+    if [[ "$line" =~ ^##\  ]]; then
+      (( ++count > 3 )) && break
+      in_section=true
+      echo ""
+      echo -e "  ${CYAN}${line#\#\# }${NC}"
+    elif [[ "$in_section" == true && -n "$line" ]]; then
+      echo "    $line"
+    fi
+  done < "$changelog"
+  echo ""
+}
+
 # ─── Version check (background, non-blocking, 24h cache) ─────────────────────
 _check_update_async() {
   local cache="${ROLL_HOME}/.update-check"

package/package.json

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

@@ -23,14 +23,27 @@ After successful Build & Deploy, extracts completed Stories from BACKLOG.md to g
 
 ## Workflow
 
-### 1. Read BACKLOG.md
+### 1. Check CHANGELOG.md
 
 ```
-Read BACKLOG.md from the project root directory.
-Extract Stories with status ✅ Completed / Done.
+CHANGELOG.md exists?
+    ├── Yes → Append mode (add current deploy's changes)
+    └── No  → Create mode (backfill all historical completed Stories)
 ```
 
-### 2. Filter for External Content
+### 2. Read BACKLOG.md
+
+```
+Append mode:
+  Extract only the Story/Fix just deployed in this session.
+
+Create mode:
+  Extract ALL Stories and Fixes with status ✅ Done.
+  Read each Story's docs/features/<feature>.md for Completed date.
+  Group entries by completion date, reverse chronological order.
+```
+
+### 3. Filter for External Content
 
 **Remove internal information:**
 - Progress tables, completion percentages
@@ -45,7 +58,23 @@ Extract Stories with status ✅ Completed / Done.
 - UX improvements (layout, interaction enhancements)
 - Performance/reliability improvements
 
-### 3. Version Number Format
+**语言：中文。** 所有 changelog 条目必须用中文撰写。
+
+**Description format:** `功能名 — 做了什么 + 用在什么场景`，一句话，精简。
+
+Good:
+```
+- **Added**: roll-jot — 一句话快速记录 bug 或想法到 backlog，不打断当前工作
+- **Fixed**: 同步时清理已删除文件，防止用户机器残留幽灵文件
+```
+
+Bad:
+```
+- **Added**: Add roll-jot skill for fast backlog capture
+- **Fixed**: Sync prunes stale files to prevent ghost files
+```
+
+### 4. Version Number Format
 
 ```
 YYYY.MM.DD
@@ -53,23 +82,37 @@ YYYY.MM.DD-1  (multiple releases on the same day)
 YYYY.MM.DD-2
 ```
 
-### 4. Generate CHANGELOG.md
+### 5. Generate CHANGELOG.md
+
+**Create mode** (first time):
+```markdown
+# Changelog
+
+## 2026.05.10
+- **Added**: E2E 自动沉淀 — 每个 Story 交付时自动写一个端到端测试，项目逐步积累可回放的 E2E 套件
+- **Fixed**: 同步时清理已删除文件，防止用户机器残留幽灵文件
+
+## 2026.05.04
+- **Added**: BB 注入模式 — 对未集成 Black Box 的页面自动注入诊断探针，统一数据采集接口
+
+## 2026.04.28
+- ...
+```
 
+**Append mode** (subsequent):
 ```markdown
 # Changelog
 
-## 2026.04.03
-- **Added**: <completed feature extracted from BACKLOG>
-- **Fixed**: <resolved bug>
-- **Improved**: <UX/performance optimization>
+## 2026.05.10    ← 新条目插入顶部
+- **Added**: Changelog 自动生成 — 每次部署后自动更新，首次运行时回填全部历史记录
 
-## 2026.04.01
+## 2026.05.04    ← 已有条目不动
 - ...
 ```
 
 **Ordering**: Most recent version first (reverse chronological)
 
-### 5. Commit Update
+### 6. Commit Update
 
 ```bash
 git add CHANGELOG.md

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

@@ -205,6 +205,52 @@ If project lacks Playwright setup:
 4. Run to create baseline
 5. Commit as separate "test infrastructure" change
 
+## CI Failure Triage
+
+When CI goes red, triage the failure into an actionable item instead of ignoring it.
+
+### Step 1: Read the CI Log
+
+```
+CI failure
+    │
+    ├── Which step failed? (lint / build / test / e2e)
+    ├── What is the error message?
+    ├── Is it reproducible locally?
+    └── Is it flaky (passes on retry)?
+```
+
+### Step 2: Classify Severity
+
+| Severity | Signal | Action |
+|----------|--------|--------|
+| Critical | Build or core tests fail, blocks all merges | Fix immediately via `$roll-fix` |
+| High | E2E test fails on a key user flow | Create FIX-XXX, fix within current sprint |
+| Medium | Visual regression, non-critical test failure | Create FIX-XXX, prioritize in backlog |
+| Low | Lint warning, flaky test (passes on retry) | Create FIX-XXX or IDEA-XXX, fix when convenient |
+
+### Step 3: Create Backlog Entry
+
+```bash
+# For fixable bugs — create FIX entry
+$roll-jot fix "CI: {step} fails — {root cause summary}"
+
+# For flaky/environmental issues — create IDEA entry
+$roll-jot idea "CI: investigate flaky {test name}"
+```
+
+### Step 4: Execute Fix
+
+```
+FIX-XXX created
+    │
+    ├── Critical / High → $roll-fix FIX-XXX (immediate)
+    ├── Medium → schedule in backlog, $roll-fix when ready
+    └── Low → backlog, fix opportunistically
+```
+
+All fixes go through `$roll-fix` TCR workflow — test, fix, review, commit, push, CI green.
+
 ## References
 
 - [Playwright Docs](https://playwright.dev/)

package/skills/roll-build/SKILL.md

@@ -263,6 +263,35 @@ MICRO-STEP {N}: {description of smallest testable change}
 
 Accumulate 3–5 micro-commits per Action. Each commit is a guaranteed working state.
 
+### Phase 5.5: E2E Deposit
+
+After TCR micro-steps pass, deposit an E2E test for this Story's core user flow.
+
+```
+E2E DEPOSIT
+
+   Step 1: Detect
+      └── Read project's existing E2E infrastructure
+          (test directories, config files, framework, naming conventions)
+
+   Step 2: Write
+      └── One E2E test covering the Story's golden path
+          (the critical user journey this Story delivers)
+
+   Step 3: Run
+      └── Execute the new E2E test
+
+   Step 4: TCR
+      ├── ✅ GREEN → git commit -m "tcr: e2e deposit for {story}"
+      └── ❌ RED   → Fix via TCR cycle until green
+```
+
+**Rules:**
+- Follow whatever E2E patterns the project already uses — framework, directory, naming
+- If no E2E infrastructure exists, reference `$roll-.qa` "Missing Test Infrastructure" section to bootstrap minimally, then deposit
+- One test per Story — covers the golden path, not exhaustive edge cases (those are unit/integration from Phase 5)
+- Each deposited E2E becomes a replayable case: CI runs it on every push, Sentinel can sample it against production
+
 ### Phase 6: Pre-Push CI Gate
 
 After all micro-steps, run full CI locally before pushing:
@@ -461,6 +490,7 @@ git push
 📊 TCR Stats: <success rate, revert count if any>
 📋 Review Gate: <self-review findings summary>
 📝 BACKLOG: <US-ID> marked ✅ Done
+📄 CHANGELOG: $roll-.changelog → updated
 
 🎉 Shipped.
 
@@ -523,6 +553,7 @@ Before creating any file or directory:
 - [ ] Story and Action clearly defined
 - [ ] Test design reviewed and approved
 - [ ] **TCR cycles completed** (all micro-steps via Test && Commit)
+- [ ] **E2E deposited** (golden path test for this Story, committed via TCR)
 - [ ] All commits are green states (no broken commits)
 - [ ] Local CI checks passed (format + lint + build + test)
 - [ ] Self-code-review passed, blocking issues fixed via TCR
@@ -533,6 +564,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`
 - [ ] Summary reported to user
 
 ---
@@ -599,5 +631,6 @@ The agent must explicitly produce (in text) before or during execution:
 - **Test Design**: scenarios, edge cases, test types
 - **Test Design Review**: coverage validation result
 - **TCR Log**: micro-step descriptions and commit count
+- **E2E Deposit**: golden path E2E test file for this Story
 - **Quality Review**: post-TCR code review result
 - **Deployment target**: where it will be verified

package/skills/roll-debug/SKILL.md

@@ -2,12 +2,12 @@
 name: roll-debug
 license: MIT
 allowed-tools: "Read, Edit, Write, Bash, Agent"
-description: Universal web debugger. Mounts a Black Box (BB) diagnostic probe on any page, collects rich diagnostics, analyzes root causes, and suggests fixes. Cleans up after itself.
+description: Universal web debugger. Mounts a Black Box (BB) diagnostic probe on any page, collects rich diagnostics, analyzes root causes, and auto-fixes when the root cause is in project source. Cleans up after itself.
 ---
 
 # Roll Debug
 
-Web debugging tool that treats the **Black Box (BB) as a diagnostic probe** — mounted when needed, unmounted when done. Combines diagnostic collection and analysis into a single workflow: **Mount → Collect → Analyze → Unmount**.
+Web debugging tool that treats the **Black Box (BB) as a diagnostic probe** — mounted when needed, unmounted when done. Combines diagnostic collection, analysis, and auto-repair into a single workflow: **Mount → Collect → Analyze → Unmount → Auto-Fix (when fixable) → Re-verify**.
 
 ## Philosophy
 
@@ -47,9 +47,6 @@ $roll-debug https://example.com/page --universal
 # Use a custom BB SDK instead of the built-in stub
 $roll-debug https://example.com/page --bb-sdk-url https://cdn.example.com/bb.js
 
-# Collect + analyze + auto-fix
-$roll-debug https://example.com/page --fix
-
 # Analyze an existing report file (skip collection)
 $roll-debug --report /tmp/bb-report.json
 
@@ -104,7 +101,37 @@ User: "Debug the page"
 └──────────────────┬──────────────────┘
                    │
                    ▼
-    Fix suggestions (or --fix to apply)
+┌─────────────────────────────────────┐
+│ 5. Auto-Fix Decision Gate           │
+│    ├── Assess root cause location   │
+│    │   and fixability               │
+│    ├── Fixable?                     │
+│    │   ├── Yes (single-file,        │
+│    │   │   bounded scope)           │
+│    │   │   → enter $roll-fix TCR    │
+│    │   │     workflow automatically │
+│    │   ├── Complex (cross-module,   │
+│    │   │   architectural)           │
+│    │   │   → create US-XXX          │
+│    │   │   → suggest $roll-build    │
+│    │   └── External (third-party    │
+│    │       API, infra)              │
+│    │       → report findings only   │
+│    └── Tell user what was found     │
+│        and what was done            │
+└──────────────────┬──────────────────┘
+                   │ (if auto-fixed)
+                   ▼
+┌─────────────────────────────────────┐
+│ 6. Re-verify (after fix)            │
+│    ├── Re-mount BB probe            │
+│    ├── Collect + analyze again      │
+│    ├── Confirm issue is resolved    │
+│    └── Unmount BB probe             │
+└──────────────────┬──────────────────┘
+                   │
+                   ▼
+    Report to user (findings + actions taken)
 ```
 
 ## Collection Modes
@@ -187,9 +214,27 @@ Report: /tmp/bb-report.json
 useEffect dependency error causing content not to load.
 Dependency `[chapter?.id]` should be `[chapter?.number]`
 
-### Suggested Fix
-Modify Player.tsx line 45, change useEffect dependency
-from `[chapter?.id]` to `[chapter?.number]`
+### Auto-Fix
+Root cause is in project source (Player.tsx:45), single-file, bounded scope.
+Entering $roll-fix TCR workflow...
+
+🧪 Test: added regression test for chapter content loading
+🔧 Fix: Player.tsx:45 — useEffect dep [chapter?.id] → [chapter?.number]
+✅ TCR: test green, committed
+🔍 Review: $roll-.review passed
+📤 Push: origin/main
+⏳ CI: green
+🚀 Deploy: https://yyy.up.railway.app
+
+🔄 Re-verifying...
+📡 Re-mounting BB probe...
+📊 Collecting data...
+   ├── Console: 0 errors
+   ├── contentLength: 2340
+   └── hasText: true
+🧹 Unmounting BB probe... done
+
+✅ Issue resolved. Content now loads correctly.
 ```
 
 ### Example 2: Reuse existing native BB
@@ -525,16 +570,38 @@ No page state is modified.
 4. **Native BB untouched** — if a page already has BB, it is reused but never unmounted.
 5. **CSP fallback** — if script injection fails (CSP), automatically falls back to Universal mode.
 
-## Integration with Build Skills
-
-After `$roll-debug` finds issues:
+## Auto-Fix Behavior
 
-```bash
-# For a single-file bug fix
-# → Create FIX-XXX in backlog
-# → $roll-fix FIX-XXX
+After diagnosis, roll-debug automatically assesses whether the root cause can be fixed — **no flag needed**. The decision is context-driven:
 
-# For a complex multi-step fix
-# → Create US-XXX in backlog
-# → $roll-build US-XXX
 ```
+Root cause identified
+    │
+    ├── In project source + single-file + bounded scope
+    │   └── AUTO-FIX: enter $roll-fix TCR workflow
+    │       ├── Write regression test (RED)
+    │       ├── Apply fix (GREEN)
+    │       ├── TCR commit
+    │       ├── $roll-.review staged
+    │       ├── Push → CI → Deploy
+    │       └── Re-mount BB → re-verify on page
+    │
+    ├── In project source + cross-module / architectural
+    │   └── ESCALATE: create US-XXX in BACKLOG.md
+    │       ├── Suggest: $roll-build US-XXX
+    │       └── Report diagnosis findings
+    │
+    └── External (third-party API, infra, CDN, DNS)
+        └── REPORT ONLY
+            ├── What was found
+            └── Suggested actions (manual or external)
+```
+
+**Quality gates preserved**: When auto-fixing, all `$roll-fix` quality gates apply — TCR, `$roll-.review`, push, CI, deploy. No shortcuts.
+
+**Re-verification**: After a successful auto-fix, roll-debug re-mounts the BB probe on the same page and re-runs diagnosis to confirm the issue is actually resolved. If the issue persists, it reports the remaining findings.
+
+**User communication**: roll-debug always tells the user:
+- What was found (root cause, severity)
+- What was done (auto-fixed / escalated / reported)
+- Why (fixability assessment reasoning)

package/skills/roll-fix/SKILL.md

@@ -318,7 +318,13 @@ Change the Status of the corresponding row from `📋 Todo` to `✅ Done`.
 - Change AC (if any) from `[ ]` to `[x]`
 - Update Files to reflect actual changed files
 
-### 12. Report
+### 12. Update Changelog
+
+```bash
+$roll-.changelog
+```
+
+### 13. Report
 
 Summarize:
 - shipped fix/enhancement
@@ -327,6 +333,7 @@ Summarize:
 - verification results
 - any residual risk
 - **BACKLOG.md updated** ✅
+- **CHANGELOG.md updated** ✅
 
 ## Required Artifacts
 

package/skills/roll-release/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: roll-release
 license: MIT
-allowed-tools: "Read, Edit, Bash(git:*), Bash(npm:*), Bash(sed:*), Bash(date:*)"
+allowed-tools: "Read, Edit, Bash(git:*), Bash(npm:*), Bash(sed:*), Bash(date:*), Bash(gh:*)"
 description: "Release skill for roll maintainers. Calculates next version (YYYY.MMDD.N format, auto-increments N from today's git tags), updates VERSION in bin/roll and package.json, commits, tags, and pushes to trigger npm auto-publish via GitHub Actions. Trigger: release, publish, 发版, 发布新版本."
 ---
 
@@ -79,7 +79,22 @@ git tag "v${version}"
 git push && git push --tags
 ```
 
-### Step 5: Publish to npm
+### Step 5: Create GitHub Release
+
+Extract the current version's changelog entries and create a GitHub Release:
+
+```bash
+# Extract release notes from CHANGELOG.md (current version's section)
+notes=$(sed -n "/^## ${version}$/,/^## /{ /^## ${version}$/d; /^## /d; p; }" CHANGELOG.md)
+
+gh release create "v${version}" \
+  --title "v${version}" \
+  --notes "${notes:-Release v${version}}"
+```
+
+This enables the background update check in `bin/roll` (`_check_update_async`), which queries the GitHub Releases API.
+
+### Step 6: Publish to npm
 
 ```bash
 npm publish --access public
@@ -87,13 +102,14 @@ npm publish --access public
 
 This will open a browser for 2FA verification. Wait for it to complete before continuing.
 
-### Step 6: Confirm
+### Step 7: Confirm
 
 After publish, show:
 ```
 ✅ Released v{version}
 🏷  Tag: v{version} pushed to origin
 📦 npm published: {package_name}@{version}   # package name read from package.json
+🐙 GitHub Release: https://github.com/{owner}/{repo}/releases/tag/v{version}
 🔗 https://www.npmjs.com/package/{package_name}
 ```
 

package/template/.github/workflows/ci.yml

@@ -30,3 +30,6 @@ jobs:
       
       - name: Test
         run: npm run test -- --run
+
+      - name: E2E Tests
+        run: npm run test:e2e --if-present