@seanyao/roll 2026.529.5 → 2026.601.2

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

@@ -13,7 +13,7 @@ After successful Build & Deploy, extracts completed Stories from .roll/backlog.m
 ## When Triggered
 
 - **Auto-triggered**: After successful deploy of `$roll-build` or `$roll-fix`
-- **Manual trigger**: When user requests "update changelog" or "generate release notes"
+- **Manual trigger**: When user requests "update changelog" / "更新 changelog"
 
 ## When Not to Use
 
@@ -122,6 +122,8 @@ CHANGELOG 只取破折号前的用户症状，丢弃破折号后的修复手段
 
 Fix 类句式参考：`<命令/功能> 不再 <之前的坏现象>`，或 `<命令/功能> 现在 <正常表现>`。内部有几个 bug 导致这一个现象，合并成一条。
 
+**归因标签**：每条 bullet 末尾加来源标签——`[loop]`（对应 `US-AUTO-*` / `FIX-*` / `US-CL-*` 等由 Loop 自动执行的故事）、`[dream]`（对应 `REFACTOR-*`，Dream 夜间扫描推入 Backlog）、无标签（人工提交或来源不明）。同一来源的多条不必重复标。
+
 ### 4. Section Header — Always `## Unreleased`
 
 **⚠️ do NOT guess version numbers.** Only the release script (maintainer-private
@@ -131,10 +133,17 @@ the moment of a real release. Until then, every new bullet goes under
 
 ```
 ## Unreleased
-- **Added**: ...new entries here...
-- **Fixed**: ...
+
+### 新功能
+- ...new entries here...
+
+### 稳定性
+- ...
 ```
 
+新条目按**感知分组**（`### 标题`）归类，不写 `**Added**` / `**Fixed**` 前缀——
+分组规则见 **Section 7**（版本段落 = GitHub Release 正文，分组结构是 changelog 自己的格式）。
+
 When the release script runs, it renames `## Unreleased` to `## v{N}` (where N
 is computed from git tags) — that's the single moment a version label gets
 assigned.
@@ -232,29 +241,37 @@ its own first draft. Set `ROLL_CHANGELOG_AUDIT_LOG` to redirect (tests only).
 
 ### 5. Generate CHANGELOG.md
 
+条目结构按 **Section 7** 的感知分组（`### 新功能` / `### 自动化流水线` / …），不用 `Added`/`Fixed`。
+
 **Create mode** (first time, no CHANGELOG.md yet):
 ```markdown
 # Changelog
 
 ## Unreleased
-- **Added**: ...current deploy's entries...
+
+### 新功能
+- ...current deploy's entries...
 
 ## 2026.05.10
-- **Added**: ...historical entries from completed Stories before today...
+- ...historical entries from completed Stories before today...
 ```
 
 **Append mode** (most common — CHANGELOG.md exists):
 
 1. Find `## Unreleased` heading at the top of CHANGELOG.md.
-2. If it exists → append new bullets under it (do NOT create a new section).
-3. If it doesn't exist → insert a fresh `## Unreleased` at the very top (right after the `# Changelog` title) with the new bullets.
+2. If it exists → append each new bullet under the **right `### 感知分组`**（已有该组就追加，没有就按 Section 7 的分组顺序插入），do NOT create a new `##` section.
+3. If it doesn't exist → insert a fresh `## Unreleased` at the very top (right after the `# Changelog` title) with the grouped bullets.
 
 ```markdown
 # Changelog
 
 ## Unreleased
-- **Added**: ...just-deployed entry appended here...
-- **Fixed**: ...another just-deployed entry...
+
+### 自动化流水线
+- ...just-deployed entry appended here... `[loop]`
+
+### 稳定性
+- ...another just-deployed entry...
 
 ## v2026.05.07      ← previous releases left untouched
 - ...
@@ -290,85 +307,79 @@ After successful deploy in `$roll-build` / `$roll-fix`:
 
 ---
 
-## 7. Release Notes 生成模式（GitHub Release 正文）
-
-`CHANGELOG.md` 里的 `## Unreleased` 条目是**原始数据**,每条对应一个故事或修复。
-发版时(release script 打 tag 前,或手动 `roll release notes`),把这些散装 bullet 整理成**给人读的 Release 正文**。
-
-这是两个不同的产物：
-- `CHANGELOG.md` — 机器写、给 `roll update` 之后展示用，条目可以多
-- GitHub Release 正文 — 给用户 / 关注者读，要分组、要有温度、要简洁
+## 7. 版本段落 = GitHub Release 正文（分组 + 措辞）
 
-### 7.1 何时触发
+Roll 里**没有独立的 "release notes"**：release notes 就是 changelog——同一份内容、
+同一个文件（`CHANGELOG.md`）。凡是有人说 "release notes"，在 Roll 里就是指 changelog。
+发版脚本（maintainer-private，`roll-meta/ops/release.sh`）把 `## Unreleased` 改名成
+`## v{N}`，把该版段落**逐字提取**作为 GitHub Release 正文——不另写格式、不另存文件
+（没有 `RELEASE_NOTES.md`）、不在发版关键路径上现场生成。
 
-- 发版脚本在 commit 之前调用本 skill 并传入 `--release-notes` flag
-- 或用户手动说"帮我整理 Release Notes"
+所以**版本段落本身就要长成 Release 正文该有的样子**。下面的分组 / 合并 / 措辞 / hard
+rules 不是"另一种格式"，就是 changelog 段落的写法——把它写好 = 同时写好了 changelog
+和"发布说明"。
 
-### 7.2 分组规则
+### 7.1 分组（取代 Added/Fixed）
 
-把当前版本的 bullet 按**用户感知**归入以下分组，每组最多 5 条，超出的合并：
+每条 bullet 按**用户感知**归入下列分组，分组用 `###` 标题，每组最多 5 条，超出的合并：
 
-| 分组标题 | 归入条件 |
+| 分组（`### 标题`） | 归入条件 |
 |---|---|
+| 新功能 | 全新命令或用户可感知的新能力 |
 | 自动化流水线 | PR 自动化、Auto-merge、CI 触发、分支管理 |
 | 可见性 | Dashboard、弹窗、实时输出、状态显示 |
 | 稳定性 | 崩溃修复、并发问题、状态误报 |
 | 工程和测试 | CI 速度、测试并行、文档工作流 |
-| 新功能 | 全新命令或用户可感知的新能力 |
-
-分组顺序：**影响日常使用的放前面**，纯工程改进放后面。
-分组少于 2 条时可以合并到相邻组，不强制保留空组。
 
-### 7.3 合并相似条目
+分组顺序：**影响日常使用的放前面**，纯工程改进放后面。某组少于 2 条可并入相邻组，不强留空组。
+**不写 `**Added**` / `**Fixed**` 前缀**——分组标题已经承担语义分类。
 
-同一功能点的多个 bullet（如"开 PR"和"Auto-merge"都在描述同一条流水线）合并为一条，用一句话说清楚整体效果，不要列两条。
+### 7.2 合并相似条目（dedup）
 
-判断标准：**用户感知到的是同一件事，就合并。**
+同一功能点的多个 bullet（如"开 PR"和"Auto-merge"都在描述同一条流水线）合并成一条，
+一句话说清整体效果。判断标准：**用户感知到的是同一件事，就合并。**
 
-### 7.4 归因标签
+### 7.3 措辞：第二人称 + 有温度
 
-在每条末尾加标签，说明是谁做的：
-
-| 标签 | 归因依据 |
-|---|---|
-| `[loop]` | 对应 `US-AUTO-*` / `FIX-*` / `US-CL-*` 故事，由 Loop 自动执行 |
-| `[dream]` | 对应 `REFACTOR-*` 故事，由 Dream 夜间扫描发现并推入 Backlog |
-| （无标签） | 人工提交，或无法确定来源 |
+- 用**第二人称**（"你不用再盯着"、"你可以随时查看"）
+- **主语是用户的感受**，不是系统行为（"不再误报" > "修复了误报逻辑"）
+- **故意模糊实现细节**：不写函数名、文件名、Phase 编号（Section 3 的过滤规则同样适用）
+- **有温度**：可以用"真的很急"、"不再越来越乱"这种口语表达
+- 每条一行，简洁优先
 
-### 7.5 措辞原则
+### 7.4 Hard rules
 
-- 用**第二人称**（"你不需要盯着"、"你可以随时查看"）
-- **主语是用户的感受**，不是系统的行为（"不再误报" > "修复了误报逻辑"）
-- **故意模糊实现细节**：不写函数名、文件名、Phase 编号
-- **有温度**：可以用"真的很急"、"不再越来越乱"这样口语化的表达
-- 每条一行，简洁优先
+- **不杜撰**：每条都能追溯到一个真实的已完成 Story / FIX / 合并 PR；CHANGELOG 里没有的改动不写。
+- **不猜版本号**：只写 `## Unreleased`（见 Section 4），版本号由发版脚本赋。
+- **不 bump / tag / 发布**：那是人执行的发版步骤，本 skill 只写 changelog。
+- **可审阅**：CHANGELOG 是提交进仓库的文件，owner 随时（尤其发版前）可直接审阅 / 编辑——
+  无需为审阅单独生成什么。
 
-### 7.6 输出格式
+### 7.5 示例
 
 ```markdown
-## <分组标题>
+## Unreleased
 
-- <条目> `[loop]`
-- <条目> `[dream]`
-- <条目>
+### 自动化流水线
+- 你不用再盯着 PR，开完自动合并 `[loop]`
 
-## <分组标题>
+### 稳定性
+- 多个 loop 不再互相打架 `[loop]`
 
-- ...
+### 新功能
+- `roll loop runs` 随时回看最近几次跑了啥 `[loop]`
 ```
 
-不需要 `**Added**` / `**Fixed**` 前缀，分组标题已经承担了语义分类的职责。
-
 ## 8. features.md 重写模式（产品 SOT）
 
 US-DOC-008 — 发版脚本（maintainer-private，位于 `roll-meta/ops/release.sh`）
-在 changelog/release-notes 生成完后会再调一次本 skill，请求"整体重写
-`.roll/features.md`"。这次调用的语义和上面两种完全不同：**不是基于本版
+在 changelog 写盘后会再调一次本 skill，请求"整体重写
+`.roll/features.md`"。这次调用的语义和上面完全不同：**不是基于本版
 Story 增量**，而是基于**项目整体当前状态**。
 
 ### 8.1 何时触发
 
-发版脚本完成 changelog/release-notes 写盘后，喂一段以
+发版脚本完成 changelog 写盘后，喂一段以
 `## 当前任务：重写 .roll/features.md（Section 8）` 开头的 prompt。
 
 ### 8.2 输入

package/skills/roll-brief/SKILL.md

@@ -8,7 +8,7 @@ description: |
   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.
+  changelog) — this is an internal digest for the product owner.
 ---
 
 # Roll Brief

package/skills/roll-build/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: roll-build
 license: MIT
+allowed-tools: "Read, Edit, Write, Glob, Grep, Bash, Skill, Agent"
 description: "Universal delivery skill. Handles any input: a US-XXX ID executes from BACKLOG via TCR; a FIX-XXX redirects to roll-fix; any other text auto-clarifies, designs, and ships as a new Story."
 ---
 
@@ -54,24 +55,25 @@ Activate when input is a `US-[A-Z]+-[0-9]+` identifier.
 
 ### Step 0: Pre-flight self-check (US-AGENT-007)
 
-Before reading the Story in depth or splitting actions, **read the Agent profile** from the story's feature md and decide whether this cycle can realistically deliver it. The check is mechanical:
+Before reading the Story in depth or splitting actions, **read the Agent profile** from the story's feature md and decide whether this cycle can realistically deliver it. The check is mechanical and turns on a single axis — the story's `est_min` estimate (US-AGENT-022 retired the old three-dimension type/est/risk routing; there is no per-agent capacity range, risk zone, or history threshold anymore):
 
 ```
 inputs:
   story.est_min       (from **Agent profile:** block, US-AGENT-001)
-  story.risk_zone     (low / medium / high)
   story.chain_depth   (0 unless already a downgrade product)
-  agent.max_est_min   (from .roll/agent-routes.yaml for the current agent)
-  history.prefer_threshold (from .roll/agent-routes.yaml)
-  history.hit_rate    (this agent × this story_type, last window_cycles)
+
+complexity tier (lib/loop_pick_agent.py, single source of truth):
+  est_min <= 8        → easy
+  8 < est_min <= 20   → default
+  est_min > 20        → hard
+  missing / illegal   → default
 
 verdict:
-  too_big when ANY of these is true:
-    1. story.est_min > agent.max_est_min   (hard capacity miss)
-    2. story.risk_zone not in agent.risk    (hard risk miss)
-    3. history.hit_rate < prefer_threshold AND story.chain_depth == 0
-       (soft signal: history says this agent's not on top of this type yet,
-        and we still have downgrade budget — don't burn a cycle)
+  too_big when:
+    story.est_min is large enough that even the `hard` tier won't fit one
+    cycle — i.e. the work plainly composes too many files / behaviours to
+    land green in a single cycle — AND story.chain_depth == 0
+    (still have downgrade budget; don't burn a cycle on a guaranteed miss).
   ok otherwise
 ```
 
@@ -110,7 +112,7 @@ exit 0
 
 If `roll-design` cannot produce ≥2 sub-stories (story is already irreducible), fall through to **US-AGENT-009 cap-hit path** by invoking `_loop_split_cap_hit` directly. The cap is purely about stopping infinite split chains; even on the first re-split, if the design step gives up, the cap-hit handler raises ALERT for human triage.
 
-> Pre-flight is honest, not paranoid: a small story (est_min ≤ 5, chain_depth=0, low risk) should almost always go `ok`. The check pays off on the long tail — stories that look small but compose tons of files, or that the current agent has historically failed.
+> Pre-flight is honest, not paranoid: a small story (est_min ≤ 8 — the `easy` tier — with chain_depth=0) should almost always go `ok`. The check pays off on the long tail — stories with a large `est_min` that, on inspection, plainly compose far more files and behaviours than one cycle can land green.
 
 ### Step 1: Read the Story
 

package/skills/roll-deck/SKILL.md

@@ -34,6 +34,8 @@ $roll-deck "How TCR keeps us honest"
 - You MUST NOT edit any other file: no README, no AGENTS.md, no backlog, no source code, no `.roll/slides/*.html`.
 - HTML rendering is `roll slides build <slug>` — never produce HTML here.
 - If `.roll/slides/<slug>/deck.md` already exists, ask the user before overwriting.
+- **Layout must come from the whitelist**: `plain`, `cards-2`, `cards-3`, `cards-4`, `compare`, `pipeline`, `timeline`, `quote`, `highlight`. Inventing a layout name makes `roll slides build` fail with `Unknown layout`.
+  **layout 必须从白名单选**：`plain` / `cards-2` / `cards-3` / `cards-4` / `compare` / `pipeline` / `timeline` / `quote` / `highlight`。自创 layout 名渲染会失败。
 
 ## Inputs
 
@@ -68,6 +70,7 @@ Stop reading when you have enough to write 18 slides with concrete evidence.
 
 Default count is `18` (or the count the template prescribes). Each slide MUST contain:
 
+- `layout` — one of the whitelist layouts (see "Layout 选择手册" below). **You MUST declare `layout:` explicitly on every slide, before `evidence:`** — this forces a deliberate choice and stops every slide collapsing to `plain`.
 - `title_en` — short English title (≤ 8 words).
 - `title_zh` — short Chinese title (≤ 16 chars).
 - `body_en` — markdown body, concise, ≤ 200 words.
@@ -86,6 +89,149 @@ Default count is `18` (or the count the template prescribes). Each slide MUST co
 
 Bilingual rule: English and Chinese MUST be on separate lines in the rendered body — never inline on the same line.
 
+## Layout 选择手册  Layout Selection Playbook
+
+Pick the layout from the **shape of the content**, not from a wish to look fancy.
+按**内容形态**选 layout，而不是为了好看硬凑。
+
+### Decision matrix  决策矩阵
+
+| Content shape  内容形态 | Pick  推荐 layout | Anti-pattern  反例（不要用） |
+|---|---|---|
+| Before/after, old vs new, "what we did vs didn't"  前后对比 / 旧 vs 新 | `compare` | `cards-2` — loses the contrast semantics  缺失对比语义 |
+| Multi-step process, pipeline, staged flow  多步骤流程 / 阶段流转 | `pipeline` | `cards-N` — order is invisible  看不出顺序 |
+| Time series, evolution, changelog  时间序列 / 演进 / changelog | `timeline` | `pipeline` — pipeline = steps, timeline = time  pipeline 表步骤、timeline 表时间 |
+| 2/3/4 parallel concepts, no internal order  2/3/4 个并列概念，无顺序 | `cards-2` / `cards-3` / `cards-4` | ≥5 items crammed in — split the slide  ≥5 项硬塞，请拆 slide |
+| A line, a testimonial, the user's own words  引言 / 金句 / 用户原话 | `quote` | `highlight` — quote has attribution, highlight is a conclusion  quote 有归属，highlight 是结论 |
+| The one key takeaway / one-line conclusion  关键结论 / 一句话总结 | `highlight` | `plain` — drowns in the paragraph  淹没在段落里 |
+| Ordinary prose, explanation, plain list  普通段落 / 解释 / 列表 | `plain` | — |
+
+**At most one layout per slide.** Do not stack layouts. And do not force a rich
+component when the content is genuinely just a paragraph — **if the content is
+really one block of prose, `plain` is the correct choice**, not a failure.
+**每张 slide 最多 1 个 layout。** 不要为了用富组件硬凑；内容真就是一段话时，`plain` 是正确答案，不是偷懒。
+
+### Worked examples  真实示例
+
+Five examples, drawn from real `site/slides/roll-introduction-v5.html` slides.
+五个示例，取自 v5 实际 slide。
+
+**1. "TCR before vs after" → `compare`**
+内容是"用 TCR 之前 vs 之后" → 选 `compare`：
+
+```markdown
+## Slide 4
+layout: compare
+title_en: "Why TCR"
+title_zh: "为什么用 TCR"
+left_title_en: "Before"
+left_title_zh: "之前"
+right_title_en: "After"
+right_title_zh: "之后"
+left_items:
+  - text_en: "Broken commits land on main"
+    text_zh: "坏提交直接进 main"
+right_items:
+  - text_en: "Every commit is green or reverted"
+    text_zh: "每个提交要么绿要么回滚"
+evidence:
+  - AGENTS.md:42
+```
+
+**2. "The Roll loop pipeline" → `pipeline`**
+内容是"idea → backlog → build → verify → release 流转" → 选 `pipeline`：
+
+```markdown
+## Slide 7
+layout: pipeline
+title_en: "The Roll Loop"
+title_zh: "Roll 循环"
+stages:
+  - title_en: "Idea"
+    title_zh: "想法"
+    desc_en: "Capture in backlog"
+    desc_zh: "落到 backlog"
+    css_class: "pipe-idea"
+  - title_en: "Build"
+    title_zh: "构建"
+    desc_en: "TCR micro-commits"
+    desc_zh: "TCR 微提交"
+    css_class: "pipe-build"
+evidence:
+  - skills/roll-loop/SKILL.md:1
+```
+
+**3. "How Roll grew over releases" → `timeline`**
+内容是"v1 → v2 → 现在的演进" → 选 `timeline`：
+
+```markdown
+## Slide 12
+layout: timeline
+title_en: "How Roll Grew"
+title_zh: "Roll 的演进"
+items:
+  - title_en: "First loop"
+    title_zh: "第一版 loop"
+    body_en: "Hourly cron executor."
+    body_zh: "每小时 cron 执行器。"
+evidence:
+  - CHANGELOG.md:1
+```
+
+**4. "Three pillars of Roll" → `cards-3`**
+内容是"三个并列支柱，无先后" → 选 `cards-3`：
+
+```markdown
+## Slide 5
+layout: cards-3
+title_en: "Three Pillars"
+title_zh: "三大支柱"
+cards:
+  - title_en: "Skills"
+    title_zh: "技能"
+    body_en: "Composable AI workflows."
+    body_zh: "可组合的 AI 工作流。"
+  - title_en: "Loop"
+    title_zh: "循环"
+    body_en: "Autonomous backlog executor."
+    body_zh: "自主 backlog 执行器。"
+  - title_en: "TCR"
+    title_zh: "TCR"
+    body_en: "Test && commit || revert."
+    body_zh: "测试通过则提交，否则回滚。"
+evidence:
+  - README.md:1
+```
+
+**5. "Kimi's verdict" → `quote`**
+内容是带归属的一句用户原话 → 选 `quote`：
+
+```markdown
+## Slide 16
+layout: quote
+title_en: "Peer Verdict"
+title_zh: "评审结论"
+text_en: "AGREE with refinement."
+text_zh: "同意，附细化意见。"
+evidence:
+  - .roll/features/authoring/slide-deck-generator.md:919
+```
+
+Whitelist field names match `lib/slides/components/README.md` — copy them
+verbatim (`left_items` / `right_items` / `stages[].css_class` / `text_en` …).
+字段名以 `lib/slides/components/README.md` 为准，原样照抄。
+
+## Known agent limitations  已知 agent 局限
+
+The layout playbook is loadable by any agent (mechanism is agent-agnostic), but
+whether the model actually *applies* the decision matrix scales with model
+strength. Claude Opus / Sonnet are the most reliable. If an agent degrades to
+"all `plain` placeholders" and ignores the matrix, note it here rather than
+blocking — quality, not mechanism, is the variable.
+layout 手册任何 agent 都读得到（机制 agnostic），但是否真按矩阵挑 layout 跟模型强度相关。Claude Opus / Sonnet 最稳；某 agent 退化成全 plain 时记到此处，不阻塞。
+
+- (No degradations recorded yet.  暂无记录。)
+
 ### 4. Write deck.md  写文件
 
 Write to `.roll/slides/<slug>/deck.md` with this structure:
@@ -105,6 +251,7 @@ author: "<from package.json author>"
 ---
 
 ## Slide 1
+layout: plain
 title_en: "..."
 title_zh: "..."
 body_en: |
@@ -119,6 +266,11 @@ evidence:
 ...
 ```
 
+Every slide declares `layout:` first (see "Layout 选择手册"); rich layouts add
+their own structured fields (e.g. `cards`, `left_items`, `stages`) in place of
+`body_en` / `body_zh`.
+每张 slide 先声明 `layout:`；富 layout 用各自的结构化字段取代 `body_en` / `body_zh`。
+
 `total_slides` MUST match the number of `## Slide N` blocks. The validator (run by `roll slides build`) will reject mismatches.
 
 Project identity fields (`pkg_name`, `repo_url`, `site_url`, `author`) are copied verbatim from `package.json` — never infer or guess these values. `roll slides build` injects them into the HTML template (cover, back cover, footer).

package/skills/roll-design/SKILL.md

@@ -682,8 +682,8 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 - Cross-context: {if touches another context, otherwise omit}
 
 **Agent profile:**
-- est_min: {1-30 整数,目标 5-10 min 一个 cycle 闭环}
-- risk_zone: {low / medium / high — 改文档 low,改用户可见行为 medium,改 loop infra 或安全/隔离基建 high}
+- est_min: {1-30 整数;一个 Story ≈ 一个 AI cycle 闭环,目标 5-10 min。这是**唯一的 loop 路由输入**——`lib/loop_pick_agent.py` 把 est_min 映射到复杂度档：≤8 → easy,8<x≤20 → default,>20 → hard;缺失/非法值 → default。est > ~15 是"再拆"信号——除非原子不可分(见 INVEST 的 S/I 校准)}
+- risk_zone: {low / medium / high — 改文档 low,改用户可见行为 medium,改 loop infra 或安全/隔离基建 high。**不参与 loop 路由**(路由只看 est_min);仅供 roll-build / roll-fix 的 pre-flight 自评(US-AGENT-007)做能力匹配参考}
 - chain_depth: 0  {若是自降级产出的子 story 则 +1,累计 ≥2 时第 3 次拒拆}
 
 **AC:**
@@ -705,9 +705,9 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 - Integration test: `tests/integration/{flow}.test.ts`
 ```
 
-> **强制规则 — Agent profile 必须填**：Split into Stories 步骤产出的每个 US 都必须带 `**Agent profile:**` 子段，est_min / risk_zone 不可省（chain_depth 默认 0）。loop 路由（US-AGENT-004）和 agent 自评（US-AGENT-007）都靠这两个字段决策，缺了就回退到 cold_start_default 并 WARN。历史 US 不强制回填。
+> **强制规则 — Agent profile 必须填**：Split into Stories 步骤产出的每个 US 都必须带 `**Agent profile:**` 子段。`est_min` 是 **loop 路由唯一输入**（`lib/loop_pick_agent.py` 的四槽复杂度路由 easy/default/hard/fallback，按 est_min 单轴决档；缺失/非法 → default 档）——务必填准。`risk_zone` 仍要填，但**不参与路由**，只供 roll-build / roll-fix 的 pre-flight 自评（US-AGENT-007）参考；`chain_depth` 默认 0。历史 US 不强制回填。
 >
-> **MUST fill** the `**Agent profile:**` block on every newly split US — `est_min` and `risk_zone` are non-optional. They drive loop routing and agent self-eval downstream.
+> **MUST fill** the `**Agent profile:**` block on every newly split US. `est_min` is the **sole loop-routing input** — `lib/loop_pick_agent.py` maps it onto a four-slot complexity tier (easy/default/hard/fallback) on the est_min axis alone (missing/illegal → default). Fill `risk_zone` too, but note it does NOT feed routing; it only informs the roll-build / roll-fix pre-flight self-eval (US-AGENT-007).
 
 ### Closing Doc-Refresh Story Template — Phase N.M 收尾文档
 
@@ -746,12 +746,19 @@ When any preceding US in the batch changes user-visible behavior, append this te
 
 ## INVEST Principles
 
+> **颗粒度校准（按 AI cycle 量纲）**：Roll 的 Story 不是"几天的活"，而是
+> **一个 AI cycle 闭环（目标 5–10 min）**。下面的 S 和 I 按这个量纲重定义，
+> 别套用传统敏捷"一个 sprint 装几个 story"的尺度。
+
 Each story must be:
-- **Independent**: Can be implemented independently
+- **Independent**: 不强求完全独立。有先后依赖就用 `depends-on:` 串成链（配合
+  `chain_depth ≤ 2` 防无限套娃）。真正要避免的是"改同一文件的并行冲突"，
+  而不是"禁止依赖"——为追求独立硬把一个 cycle 的活摊成几个反而更糟。
 - **Negotiable**: Scope is negotiable
 - **Valuable**: Provides value to the user
 - **Estimable**: Effort can be estimated
-- **Small**: Small enough for fast delivery
+- **Small**: **一个 Story ≈ 一个 AI cycle 闭环（目标 5–10 min）**。S 是 cycle 量纲，
+  装不进一个 cycle 就拆；`est_min > ~15` 是"再拆"信号——除非原子不可分。
 - **Testable**: Can be tested and verified
 
 ## Backlog Structure