@seanyao/roll 2026.518.4 → 2026.519.2

package/lib/roll-status.py

@@ -293,8 +293,8 @@ def _render_this_project(d: Dict[str, Any]) -> None:
         print(line)
 
     _file_row("AGENTS.md",        d["project_has_agents"])
-    _file_row("BACKLOG.md",       d["project_has_backlog"])
-    _file_row("docs/features/",   d["project_features_count"] > 0,
+    _file_row(".roll/backlog.md",       d["project_has_backlog"])
+    _file_row(".roll/features/",   d["project_features_count"] > 0,
               f"{d['project_features_count']} feature docs")
 
     # Loop & dream launchd
@@ -329,14 +329,14 @@ def _live_data() -> Dict[str, Any]:
             "skills":   _ai_skill_count(e),
         })
     templates = [(t, _template_count(t)) for t in TEMPLATES]
-    feat_dir = Path("docs/features")
+    feat_dir = Path(".roll/features")
     return dict(
         conventions       = _global_conventions(),
         ai_clients        = ai_clients,
         templates         = templates,
         skills_installed  = _skills_installed(),
         project_has_agents  = Path("AGENTS.md").exists(),
-        project_has_backlog = Path("BACKLOG.md").exists(),
+        project_has_backlog = Path(".roll/backlog.md").exists(),
         project_features_count = sum(1 for _ in feat_dir.glob("*.md")) if feat_dir.exists() else 0,
         loop_state  = _launchd_state("loop", slug),
         dream_state = _launchd_state("dream", slug),

package/package.json

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

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

@@ -3,12 +3,12 @@ hidden: true
 name: roll-.changelog
 license: MIT
 allowed-tools: "Read, Edit, Write, Bash(git:*)"
-description: After build completion, extracts completed Stories from BACKLOG.md to generate CHANGELOG.md. Auto-triggered after successful deploy, keeping the external changelog in sync with the internal backlog.
+description: After build completion, extracts completed Stories from .roll/backlog.md to generate CHANGELOG.md. Auto-triggered after successful deploy, keeping the external changelog in sync with the internal backlog.
 ---
 
 # WK Generate Changelog
 
-After successful Build & Deploy, extracts completed Stories from BACKLOG.md to generate a user-friendly `CHANGELOG.md`.
+After successful Build & Deploy, extracts completed Stories from .roll/backlog.md to generate a user-friendly `CHANGELOG.md`.
 
 ## When Triggered
 
@@ -31,7 +31,7 @@ CHANGELOG.md exists?
     └── No  → Create mode (backfill all historical completed Stories)
 ```
 
-### 2. Read BACKLOG.md
+### 2. Read .roll/backlog.md
 
 ```
 Append mode:
@@ -39,7 +39,7 @@ Append mode:
 
 Create mode:
   Extract ALL Stories and Fixes with status ✅ Done.
-  Read each Story's docs/features/<feature>.md for Completed date.
+  Read each Story's .roll/features/<feature>.md for Completed date.
   Group entries by completion date, reverse chronological order.
 ```
 
@@ -361,25 +361,25 @@ After successful deploy in `$roll-build` / `$roll-fix`:
 ## 8. features.md 重写模式（产品 SOT）
 
 US-DOC-008 — `scripts/release.sh` 在 changelog/release-notes 生成完后会再
-调一次本 skill，请求"整体重写 `docs/features.md`"。这次调用的语义和上面
+调一次本 skill，请求"整体重写 `.roll/features.md`"。这次调用的语义和上面
 两种完全不同：**不是基于本版 Story 增量**，而是基于**项目整体当前状态**。
 
 ### 8.1 何时触发
 
 release.sh 完成 changelog/release-notes 写盘后，喂一段以
-`## 当前任务：重写 docs/features.md（Section 8）` 开头的 prompt。
+`## 当前任务：重写 .roll/features.md（Section 8）` 开头的 prompt。
 
 ### 8.2 输入
 
 prompt 会包含：
-- 当前 `docs/features.md`（可能为空，可能上一版本的）
-- 当前 `BACKLOG.md` 全文（Epic / Feature 分组结构）
-- 当前 `docs/features/` 目录清单
+- 当前 `.roll/features.md`（可能为空，可能上一版本的）
+- 当前 `.roll/backlog.md` 全文（Epic / Feature 分组结构）
+- 当前 `.roll/features/` 目录清单
 - 当前版本号
 
 ### 8.3 输出契约
 
-把整个 `docs/features.md` 写出来。结构固定为三段：
+把整个 `.roll/features.md` 写出来。结构固定为三段：
 
 ```
 # Roll — Features
@@ -399,7 +399,7 @@ prompt 会包含：
 ## Features by Epic
 
 ### <Epic 名>
-- [<Feature 名>](docs/features/<file>.md) — 1 句话描述
+- [<Feature 名>](.roll/features/<file>.md) — 1 句话描述
 - <Feature 名> — 1 句话描述（缺 deep doc 时不加链接）
 
 ### <Epic 名>
@@ -414,7 +414,7 @@ prompt 会包含：
 
 - **Catalog 必须列出 BACKLOG 中所有 `### Feature:` 出现的 Feature 名**
   （即使没有 deep doc 也要列）
-- Feature 名跟 `docs/features/<file>.md` 文件名一致时，加链接到该 md
+- Feature 名跟 `.roll/features/<file>.md` 文件名一致时，加链接到该 md
 - 没有对应 deep doc 的 Feature，**只写 plain text 不加链接**
 - **Planning distinction（US-DOC-011）**：
   - 该 Feature 下**所有** Story 均为 `📋 Todo` → 在描述末尾追加 `*(规划中)*`
@@ -424,7 +424,7 @@ prompt 会包含：
     `_enforce_planning_markers`，即使本规则被 AI 漏掉也会自动补 `*(规划中)*`；
     规则的权威实现是 release.sh 里的纯 shell 函数，prompt 这条只是软提示
 - 描述写 1 句话 **产品视角**：用户能用它做什么，避免实现细节
-- **语言：单一中文**。Feature 名（如 `roll-loop` / `Cross-Agent Peer Review`）和命令、环境变量等术语保留英文原样；描述句一律中文。**不要**在条目下追加英文翻译行（早期 v517.x 双语混排版式已废弃，理由：扫读困难、维护翻倍、与 `docs/guide/en|zh/` 平行目录约定不一致；英文受众走 site 端 i18n）
+- **语言：单一中文**。Feature 名（如 `roll-loop` / `Cross-Agent Peer Review`）和命令、环境变量等术语保留英文原样；描述句一律中文。**不要**在条目下追加英文翻译行（早期 v517.x 双语混排版式已废弃，理由：扫读困难、维护翻倍、与 `guide/en|zh/` 平行目录约定不一致；英文受众走 site 端 i18n）
 - 分组用 BACKLOG 的 Epic 名，原序，不重排
 - Core Highlights 从所有 Features 里挑 3-5 个最能代表产品定位的，
   描述用 bold 标 Feature 名后接说明；不照搬 catalog 文案

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

@@ -8,7 +8,7 @@ description: |
   (cron or GitHub Actions), not invoked by users directly. Detects dead code,
   architectural drift from domain model, pruning candidates, emerging patterns,
   doc coverage gaps, and doc staleness (文档新鲜度). Outputs REFACTOR entries
-  to BACKLOG.md and a daily log to docs/dream/.
+  to .roll/backlog.md and a daily log to .roll/dream/.
   Distinct from roll-sentinel: sentinel monitors runtime behavior; dream reviews
   code structure and architectural health.
 ---
@@ -56,7 +56,7 @@ 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/`:
+Compare current code structure against the domain model in `.roll/domain/`:
 
 ```bash
 # Read context-map.md and ubiquitous-language.md if they exist
@@ -69,7 +69,7 @@ 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.
 
-**Distinction from Scan 6C**: Scan 2 flags *import boundary violations* (cross-context coupling). Scan 6C flags *missing documentation entries* (module exists but has no entry in `docs/domain/*.md`). Never double-flag — Scan 2 and Scan 6C are orthogonal checks.
+**Distinction from Scan 6C**: Scan 2 flags *import boundary violations* (cross-context coupling). Scan 6C flags *missing documentation entries* (module exists but has no entry in `.roll/domain/*.md`). Never double-flag — Scan 2 and Scan 6C are orthogonal checks.
 
 ### Scan 3 — Pruning Candidates
 
@@ -106,18 +106,18 @@ Check documentation structure against the conventions in `AGENTS.md § Documenta
 
 **Check A — BACKLOG Done stories missing guide/en/ docs:**
 
-Scan BACKLOG.md for features with multiple ✅ Done stories. For each feature epic, check whether a corresponding `docs/guide/en/<topic>.md` exists. If a feature has ≥3 Done stories and no guide doc, flag it.
+Scan .roll/backlog.md for features with multiple ✅ Done stories. For each feature epic, check whether a corresponding `guide/en/<topic>.md` exists. If a feature has ≥3 Done stories and no guide doc, flag it.
 
 **Check B — guide/en/ files missing guide/zh/ translations:**
 
 ```bash
-for f in docs/guide/en/*.md; do
+for f in guide/en/*.md; do
   base=$(basename "$f")
-  [ ! -f "docs/guide/zh/$base" ] && echo "missing ZH: $base"
+  [ ! -f "guide/zh/$base" ] && echo "missing ZH: $base"
 done
 ```
 
-Flag any `docs/guide/en/<topic>.md` that has no matching `docs/guide/zh/<topic>.md`, provided the EN file has existed since before the most recent git tag (i.e., at least one release cycle old).
+Flag any `guide/en/<topic>.md` that has no matching `guide/zh/<topic>.md`, provided the EN file has existed since before the most recent git tag (i.e., at least one release cycle old).
 
 **Check C — stray files in docs/ root (根目录散落文件):**
 
@@ -129,9 +129,9 @@ Flag any `.md` file directly in `docs/` root (allowed subdirs: `guide/`, `domain
 
 **Check D — features.md Feature Coverage (US-DOC-009):**
 
-Dependency gate: skip when `docs/features.md` does not exist.
+Dependency gate: skip when `.roll/features.md` does not exist.
 
-Parse BACKLOG.md for all `### Feature: <name>` groups that contain ≥1 ✅ Done story. Parse `docs/features.md` for Feature names. If any Feature group with Done stories is absent from `docs/features.md`, the catalog is stale — flag as REFACTOR:
+Parse .roll/backlog.md for all `### Feature: <name>` groups that contain ≥1 ✅ Done story. Parse `.roll/features.md` for Feature names. If any Feature group with Done stories is absent from `.roll/features.md`, the catalog is stale — flag as REFACTOR:
 
 ```markdown
 | REFACTOR-XXX | features.md 功能目录落后于 BACKLOG，N 个已完成功能区未收录，用户无法通过产品目录发现这些功能 — flagged by dream YYYY-MM-DD | 📋 Todo |
@@ -168,14 +168,14 @@ When deployed, each finding produces a REFACTOR entry with `$roll-doc` as execut
 Flag source files whose owning doc is >30 days stale:
 
 ```bash
-# For each file listed in docs/features/*.md or README.md "## Files:" sections:
+# For each file listed in .roll/features/*.md or README.md "## Files:" sections:
 #   owner_doc_commit = git log -1 --format="%ci" -- <doc_file>
 #   source_commit    = git log -1 --format="%ci" -- <source_file>
 #   lag_days = (source_commit - owner_doc_commit) in days
 #   if lag_days > 30 AND doc contains at least one specific file path reference → flag
 ```
 
-The "owner doc" for a source file is the nearest `README.md` or `docs/features/*.md` that lists the file path in a `## Files:` section. Skip docs that contain only conceptual descriptions (no specific file path references) — they cannot be objectively stale.
+The "owner doc" for a source file is the nearest `README.md` or `.roll/features/*.md` that lists the file path in a `## Files:` section. Skip docs that contain only conceptual descriptions (no specific file path references) — they cannot be objectively stale.
 
 #### Check B — Undocumented ENV Vars
 
@@ -204,13 +204,13 @@ This is distinct from Scan 2 (which checks *import violations*) — Scan 6C chec
 ```bash
 # Walk all non-excluded directories
 # For each dir with >= 3 non-hidden, non-.md source files:
-#   check if any docs/domain/*.md contains the directory name
+#   check if any .roll/domain/*.md contains the directory name
 #   if not found → flag as "existence drift"
 ```
 
 Exclusions: `node_modules/`, `.git/`, `dist/`, `build/`, `.shared/`, `docs/`, `tests/`.
 
-Flag directories with ≥3 source files and zero name-match in `docs/domain/*.md`.
+Flag directories with ≥3 source files and zero name-match in `.roll/domain/*.md`.
 
 #### Dream Log Section
 
@@ -220,16 +220,16 @@ Add after `## 文档覆盖度` section:
 ## 文档新鲜度
 - 滞后文档：{N} 个（超过 30 天未更新但绑定了代码文件）
 - 未记录 ENV 变量：{N} 个（出现 ≥5 次但无文档）
-- 架构文档缺失模块：{N} 个（≥3 个源文件的目录未出现在 docs/domain/）
+- 架构文档缺失模块：{N} 个（≥3 个源文件的目录未出现在 .roll/domain/）
 {发现内容列表 或 "文档新鲜度良好，无滞后或缺失项。"}
 ```
 
 ## Output
 
-### REFACTOR Entry (BACKLOG.md)
+### REFACTOR Entry (.roll/backlog.md)
 
 For each finding that warrants action, append one row to the `## ♻️ Refactor`
-section of BACKLOG.md:
+section of .roll/backlog.md:
 
 ```markdown
 | REFACTOR-XXX | {one-line description} — flagged by dream {YYYY-MM-DD} | 📋 Todo |
@@ -240,7 +240,7 @@ section of BACKLOG.md:
 **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)
+### Dream Log (.roll/dream/YYYY-MM-DD.md)
 
 Always write a log, even when no REFACTOR entries are created. Output uses
 Chinese to align with roll-brief style — easier for the morning reader to scan
@@ -283,7 +283,7 @@ without context switching:
 扫描完成后立即提交，把 dream 发现纳入 git 历史，便于晨报追溯：
 
 ```bash
-git add BACKLOG.md docs/dream/YYYY-MM-DD.md
+git add .roll/backlog.md .roll/dream/YYYY-MM-DD.md
 # 有 REFACTOR 条目时：
 git commit -m "chore: dream scan YYYY-MM-DD — {N} REFACTOR entries"
 # 无发现时：
@@ -291,9 +291,9 @@ git commit -m "chore: dream scan YYYY-MM-DD — no findings"
 git push origin main
 ```
 
-- BACKLOG.md 和 dream 日志必须在**同一个 commit** 里入库，避免出现"REFACTOR 已加但日志找不到"或反过来的撕裂状态
+- .roll/backlog.md 和 dream 日志必须在**同一个 commit** 里入库，避免出现"REFACTOR 已加但日志找不到"或反过来的撕裂状态
 - 写文件失败时不要执行 commit；保持工作区干净，由调度器负责重试
-- 仅 `BACKLOG.md` 和 `docs/dream/YYYY-MM-DD.md` 入 commit，不要顺带带入其他无关变更
+- 仅 `.roll/backlog.md` 和 `.roll/dream/YYYY-MM-DD.md` 入 commit，不要顺带带入其他无关变更
 
 ## Scheduler Configuration
 
@@ -308,7 +308,7 @@ The cron entry is generated using the configured agent — no manual cron editin
 
 If the scan fails partway through:
 
-1. Write partial results to `docs/dream/YYYY-MM-DD.md` with a `## 状态：部分完成` header
+1. Write partial results to `.roll/dream/YYYY-MM-DD.md` with a `## 状态：部分完成` header
 2. Do not write incomplete REFACTOR entries to BACKLOG
 3. Log the error to `~/.shared/roll/dream/error.log`
 

package/skills/roll-brief/SKILL.md

@@ -62,25 +62,25 @@ $roll-brief --feature auth     # scoped to one feature
 
 ```bash
 # Find timestamp of last brief
-ls docs/briefs/ | sort | tail -1
+ls .roll/briefs/ | sort | tail -1
 
-# Read BACKLOG.md — collect all status changes since last brief
+# Read .roll/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:
+From .roll/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/`
-- **Doc coverage**: compute from `docs/guide/en/` and `docs/guide/zh/`:
-  - EN coverage = number of files in `docs/guide/en/`
-  - ZH translation rate = files in `docs/guide/zh/` ÷ files in `docs/guide/en/` × 100%
+- **Doc coverage**: compute from `guide/en/` and `guide/zh/`:
+  - EN coverage = number of files in `guide/en/`
+  - ZH translation rate = files in `guide/zh/` ÷ files in `guide/en/` × 100%
 
 ### Step 3 — Assess Release Readiness
 
@@ -98,8 +98,8 @@ A simple heuristic — not a gate, just a signal for the human:
 
 ### Step 4 — Write Brief
 
-文件命名：`docs/briefs/YYYY-MM-DD-{NN}.md`，NN 为当日序号（01 起，零填充两位）。
-计算方式：`ls docs/briefs/YYYY-MM-DD-*.md 2>/dev/null | wc -l`，+1 即为本次序号。
+文件命名：`.roll/briefs/YYYY-MM-DD-{NN}.md`，NN 为当日序号（01 起，零填充两位）。
+计算方式：`ls .roll/briefs/YYYY-MM-DD-*.md 2>/dev/null | wc -l`，+1 即为本次序号。
 
 全部用中文输出。**省略空 section**（无内容时连标题一起不输出）：
 
@@ -129,7 +129,7 @@ A simple heuristic — not a gate, just a signal for the human:
 
 <!-- 仅当 roll-.dream 有新发现时输出 -->
 ## 悟见
-{来自 docs/dream/ 的摘要}
+{来自 .roll/dream/ 的摘要}
 
 <!-- 仅当有 ESCALATE 告警时输出 -->
 ## 需人工介入
@@ -165,21 +165,21 @@ A simple heuristic — not a gate, just a signal for the human:
 写完文件后立即提交，让简报进入 git 历史，便于后续追溯与跨会话审计：
 
 ```bash
-git add docs/briefs/YYYY-MM-DD-NN.md
+git add .roll/briefs/YYYY-MM-DD-NN.md
 git commit -m "docs: roll-brief YYYY-MM-DD-NN — {触发原因}"
 git push origin main
 ```
 
 - 触发原因来自调用上下文（Feature 完成 / 每日 / 手动 / `--feature` / `--since`），用一句话填入
 - 写文件失败时不要执行 commit；保持工作区干净，由调用方处理重试
-- 仅 `docs/briefs/` 下新文件入 commit，不要顺带带入其他无关变更
+- 仅 `.roll/briefs/` 下新文件入 commit，不要顺带带入其他无关变更
 
 ### Step 5 — Notify
 
 写完文件后在终端或 CI 日志中打印简报路径：
 
 ```
-📋 简报已生成：docs/briefs/2026-05-10-01.md
+📋 简报已生成：.roll/briefs/2026-05-10-01.md
    发布就绪：✅ 可发版
 ```
 

package/skills/roll-build/SKILL.md

@@ -54,7 +54,7 @@ Activate when input is a `US-[A-Z]+-[0-9]+` identifier.
 
 ### Step 1: Read the Story
 
-1. Open `BACKLOG.md`, find the US row, follow the link to `docs/features/<feature>.md`
+1. Open `.roll/backlog.md`, find the US row, follow the link to `.roll/features/<feature>.md`
 2. Read the full AC / Files / Dependencies section
 3. If a plan doc (`<feature>-plan.md`) exists, read it for context
 
@@ -160,8 +160,8 @@ Wait for the user's response before editing files. If the user does not object w
 ### Phase 2: Create US / Actions
 
 - Use `$roll-design` to split vague request into INVEST-compliant User Stories
-- Insert US into `BACKLOG.md` under the relevant Epic > Feature group
-- If a new `docs/features/<feature>.md` is needed, create it
+- Insert US into `.roll/backlog.md` under the relevant Epic > Feature group
+- If a new `.roll/features/<feature>.md` is needed, create it
 
 After creation, switch to **Story mode** and execute the first US immediately.
 
@@ -275,19 +275,19 @@ While implementing, watch for these signals:
 When any signal appears, **do not stop — flag it**:
 
 ```bash
-# 1. Append to BACKLOG.md under ## ♻️ Refactor
+# 1. Append to .roll/backlog.md under ## ♻️ Refactor
 # REFACTOR-XXX | <one-line description> | 📋 Todo
 
-# 2. Append a brief entry to docs/features/refactor-log.md
+# 2. Append a brief entry to .roll/features/refactor-log.md
 ```
 
-**REFACTOR entry format in BACKLOG.md:**
+**REFACTOR entry format in .roll/backlog.md:**
 
 ```markdown
 | REFACTOR-001 | {one-line plain-language description} | 📋 Todo |
 ```
 
-描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `docs/features/refactor-log.md`。
+描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `.roll/features/refactor-log.md`。
 
 **refactor-log.md entry format:**
 
@@ -504,16 +504,16 @@ Follow the repo's deployment path (Vercel / Railway / etc.) and record the deplo
 
 Both locations must be updated — neither can be skipped:
 
-**① Update BACKLOG.md index row (Status column):**
+**① Update .roll/backlog.md index row (Status column):**
 
 ```markdown
-| [US-{ID}](docs/features/<feature>.md#us-{id}) | {Title} | ✅ Done |
+| [US-{ID}](.roll/features/<feature>.md#us-{id}) | {Title} | ✅ Done |
 ```
 
 Change the Status from `📋 Todo` or `🔨 In Progress` (whichever the row currently shows) to `✅ Done`. When invoked by `roll-loop`, the row will already be `🔨 In Progress` — that is the expected starting state, and the transition is the same Edit operation.
 For Fly mode: first append an index row under the appropriate Epic > Feature group, then mark it done.
 
-**② Update `docs/features/<feature>.md` US section:**
+**② Update `.roll/features/<feature>.md` US section:**
 
 ```markdown
 ## US-{ID} {Story Title} ✅
@@ -544,7 +544,7 @@ it in the completion commit so no separate changelog commit is created.
 $roll-.changelog
 
 # 2. Commit BACKLOG + feature doc + CHANGELOG.md together
-git add BACKLOG.md docs/features/ CHANGELOG.md
+git add .roll/backlog.md .roll/features/ CHANGELOG.md
 git commit -m "docs: mark {US-ID} as completed"
 git push
 ```
@@ -614,7 +614,7 @@ Before creating any file or directory:
    - No "while I'm here" refactors unless in a separate TCR cycle
 
 7. **Always update BACKLOG status**
-   - BACKLOG.md index row and `docs/features/<feature>.md` US section are both required
+   - .roll/backlog.md index row and `.roll/features/<feature>.md` US section are both required
    - Neither can be skipped
 
 ---
@@ -633,8 +633,8 @@ Before creating any file or directory:
 - [ ] Deployed to production
 - [ ] Online verification performed
 - [ ] **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)
+- [ ] **.roll/backlog.md index status updated** (📋 → ✅, REQUIRED)
+- [ ] **`.roll/features/<feature>.md` US section updated** (Completed date + [x] ACs, REQUIRED)
 - [ ] **CHANGELOG.md staged and bundled** into completion commit via `$roll-.changelog` in Phase 11 (REQUIRED)
 - [ ] Summary reported to user
 
@@ -685,7 +685,7 @@ When complex state management is error-prone → consider full reset + re-initia
 roll-build   → ship anything (new idea, US-ID, free-text request)
 roll-fix     → fix a specific known bug (FIX-XXX / BUG-XXX)
 roll-design  → plan and design before building (no code output)
-roll-idea    → fast capture a bug or idea into BACKLOG.md
+roll-idea    → fast capture a bug or idea into .roll/backlog.md
 roll-.clarify → passive scope clarification for vague build requests
 ```
 

package/skills/roll-debug/SKILL.md

@@ -587,7 +587,7 @@ Root cause identified
     │       └── Re-mount BB → re-verify on page
     │
     ├── In project source + cross-module / architectural
-    │   └── ESCALATE: create US-XXX in BACKLOG.md
+    │   └── ESCALATE: create US-XXX in .roll/backlog.md
     │       ├── Suggest: $roll-build US-XXX
     │       └── Report diagnosis findings
     │