@seanyao/roll 2026.521.2 → 2026.522.1

package/lib/slides-validate.py

@@ -0,0 +1,169 @@
+#!/usr/bin/env python3
+"""
+US-DECK-002: deck.md schema + grounding validator.
+
+Reads a `deck.md` file, parses it with the same parser used by the renderer
+(`lib/slides-render.py`), and verifies:
+
+  1. Required frontmatter fields are present:
+       template, slug, title_en, title_zh, total_slides, created
+  2. frontmatter.total_slides matches the actual `## Slide N` section count.
+  3. Each slide has non-empty title_en / title_zh / body_en / body_zh.
+  4. Grounding threshold: at least ceil(N/3) evidence citations across all
+     slides (i.e. >= 1 per 3 slides). If the deck has fewer, the validator
+     exits non-zero with a ⚠️ grounding warning so callers (e.g.
+     `roll slides build`) can flag it.
+
+Usage:
+    python3 slides-validate.py <deck.md>
+
+Exit codes:
+    0   valid (schema OK + grounding threshold met)
+    1   schema error (missing field, mismatch, missing slide body, etc.)
+    2   grounding warning (schema OK but evidence below threshold)
+    3   file not found / unreadable / parse error
+
+Error messages are written to stderr in English + Chinese (Roll bilingual
+convention).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import math
+import sys
+from pathlib import Path
+
+
+REQUIRED_FRONTMATTER = (
+    "template",
+    "slug",
+    "title_en",
+    "title_zh",
+    "total_slides",
+    "created",
+)
+REQUIRED_SLIDE_KEYS = ("title_en", "title_zh", "body_en", "body_zh")
+
+
+def _load_renderer():
+    """Import lib/slides-render.py as a module (hyphenated filename, so we
+    can't `import slides_render` directly)."""
+    here = Path(__file__).resolve().parent
+    spec = importlib.util.spec_from_file_location(
+        "slides_render", str(here / "slides-render.py")
+    )
+    if spec is None or spec.loader is None:
+        raise ImportError("could not load slides-render.py")
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def err(msg_en: str, msg_zh: str = "") -> None:
+    print(f"[slides-validate] {msg_en}", file=sys.stderr)
+    if msg_zh:
+        print(f"[slides-validate] {msg_zh}", file=sys.stderr)
+
+
+def validate_frontmatter(fm: dict) -> list[str]:
+    errors: list[str] = []
+    for key in REQUIRED_FRONTMATTER:
+        if key not in fm or fm[key] == "" or fm[key] is None:
+            errors.append(f"missing required frontmatter field: {key}")
+    if "total_slides" in fm and not isinstance(fm["total_slides"], int):
+        errors.append(
+            f"total_slides must be an integer, got "
+            f"{type(fm['total_slides']).__name__}: {fm['total_slides']!r}"
+        )
+    return errors
+
+
+def validate_slides(fm: dict, slides: list[dict]) -> list[str]:
+    errors: list[str] = []
+    actual = len(slides)
+    declared = fm.get("total_slides")
+    if isinstance(declared, int) and declared != actual:
+        errors.append(
+            f"total_slides mismatch: frontmatter declares {declared} but "
+            f"found {actual} `## Slide N` sections"
+        )
+    for slide in slides:
+        n = slide.get("number", "?")
+        for key in REQUIRED_SLIDE_KEYS:
+            v = slide.get(key)
+            if v is None or (isinstance(v, str) and v.strip() == ""):
+                errors.append(f"slide {n}: missing or empty {key}")
+    return errors
+
+
+def evaluate_grounding(slides: list[dict]) -> tuple[int, int, bool]:
+    """
+    Return (citations, threshold, meets_threshold).
+
+    The threshold is `ceil(len(slides) / 3)` — i.e. at least one evidence
+    citation per three slides. An empty deck trivially meets the threshold
+    (threshold = 0).
+    """
+    citations = 0
+    for slide in slides:
+        ev = slide.get("evidence")
+        if isinstance(ev, list):
+            citations += len(ev)
+    threshold = math.ceil(len(slides) / 3) if slides else 0
+    return citations, threshold, citations >= threshold
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        err(
+            "usage: slides-validate.py <deck.md>",
+            "用法: slides-validate.py <deck.md>",
+        )
+        return 3
+
+    path = Path(argv[1])
+    if not path.is_file():
+        err(f"deck file not found: {path}", f"未找到 deck 文件：{path}")
+        return 3
+
+    try:
+        renderer = _load_renderer()
+    except Exception as e:
+        err(f"could not load renderer module: {e}")
+        return 3
+
+    try:
+        src = path.read_text(encoding="utf-8")
+        fm, body = renderer.parse_frontmatter(src)
+        slides = renderer.parse_slides(body)
+    except (ValueError, OSError) as e:
+        err(f"failed to parse deck.md: {e}", "解析 deck.md 失败")
+        return 3
+
+    schema_errors: list[str] = []
+    schema_errors += validate_frontmatter(fm)
+    schema_errors += validate_slides(fm, slides)
+
+    if schema_errors:
+        for e in schema_errors:
+            err(e)
+        return 1
+
+    citations, threshold, ok = evaluate_grounding(slides)
+    if not ok:
+        err(
+            f"⚠️ grounding below threshold: {citations} evidence citation(s) "
+            f"for {len(slides)} slides (need >= {threshold}). "
+            f"Each slide group of 3 must include at least one evidence entry.",
+            f"⚠️ 证据引用不足：{len(slides)} 张幻灯片仅有 {citations} 条 evidence，"
+            f"至少需要 {threshold} 条（每 3 张 ≥ 1 条）。",
+        )
+        return 2
+
+    # Valid — silent success.
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/package.json

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

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

@@ -19,7 +19,7 @@ After successful Build & Deploy, extracts completed Stories from .roll/backlog.m
 
 - Generating commit messages or PR descriptions — this skill only runs post-deploy
 - Recording dev diary / moments (use `$roll-notes`)
-- Bumping package version (use the project's release script, e.g. `scripts/release.sh`)
+- Bumping package version (use the project's release script — Roll's lives in `roll-meta/ops/release.sh`)
 
 ## Workflow
 
@@ -59,7 +59,7 @@ CHANGELOG 只取破折号前的用户症状，丢弃破折号后的修复手段
 - 测试基建（teardown 清理、test isolation、bats helper、CI 时序）
 - prompt / SKILL.md 内部契约（schema 锁定、enum 强制、contract test）
 - 内部重构（提取函数、变量改名、目录调整）
-- 只有开发者会遇到的 bug（release.sh 自身逻辑、TCR 节奏调整）
+- 只有开发者会遇到的 bug（发版脚本自身逻辑、TCR 节奏调整）
 - 任何"用户体验不变"的改动
 
 判断准则：**如果用户读了这条记录，他不会改变使用方式，就别写。**
@@ -124,9 +124,10 @@ Fix 类句式参考：`<命令/功能> 不再 <之前的坏现象>`，或 `<命
 
 ### 4. Section Header — Always `## Unreleased`
 
-**⚠️ do NOT guess version numbers.** Only `scripts/release.sh` assigns concrete
-versions, and it only does so at the moment of a real release. Until then,
-every new bullet goes under `## Unreleased` at the top of CHANGELOG.md.
+**⚠️ do NOT guess version numbers.** Only the release script (maintainer-private
+in `roll-meta/ops/release.sh`) assigns concrete versions, and it only does so at
+the moment of a real release. Until then, every new bullet goes under
+`## Unreleased` at the top of CHANGELOG.md.
 
 ```
 ## Unreleased
@@ -134,8 +135,8 @@ every new bullet goes under `## Unreleased` at the top of CHANGELOG.md.
 - **Fixed**: ...
 ```
 
-When `release.sh` runs, it renames `## Unreleased` to `## v{N}` (where N is
-computed from git tags) — that's the single moment a version label gets
+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.
 
 Do NOT read `package.json` version, do NOT call `git describe`, do NOT invent
@@ -291,8 +292,8 @@ After successful deploy in `$roll-build` / `$roll-fix`:
 
 ## 7. Release Notes 生成模式（GitHub Release 正文）
 
-`CHANGELOG.md` 里的 `## Unreleased` 条目是**原始数据**，每条对应一个故事或修复。
-发版时（`release.sh` 打 tag 前，或手动 `roll release notes`），把这些散装 bullet 整理成**给人读的 Release 正文**。
+`CHANGELOG.md` 里的 `## Unreleased` 条目是**原始数据**,每条对应一个故事或修复。
+发版时(release script 打 tag 前,或手动 `roll release notes`),把这些散装 bullet 整理成**给人读的 Release 正文**。
 
 这是两个不同的产物：
 - `CHANGELOG.md` — 机器写、给 `roll update` 之后展示用，条目可以多
@@ -300,7 +301,7 @@ After successful deploy in `$roll-build` / `$roll-fix`:
 
 ### 7.1 何时触发
 
-- `release.sh` 在 commit 之前调用本 skill 并传入 `--release-notes` flag
+- 发版脚本在 commit 之前调用本 skill 并传入 `--release-notes` flag
 - 或用户手动说"帮我整理 Release Notes"
 
 ### 7.2 分组规则
@@ -360,13 +361,14 @@ After successful deploy in `$roll-build` / `$roll-fix`:
 
 ## 8. features.md 重写模式（产品 SOT）
 
-US-DOC-008 — `scripts/release.sh` 在 changelog/release-notes 生成完后会再
-调一次本 skill，请求"整体重写 `.roll/features.md`"。这次调用的语义和上面
-两种完全不同：**不是基于本版 Story 增量**，而是基于**项目整体当前状态**。
+US-DOC-008 — 发版脚本（maintainer-private，位于 `roll-meta/ops/release.sh`）
+在 changelog/release-notes 生成完后会再调一次本 skill，请求"整体重写
+`.roll/features.md`"。这次调用的语义和上面两种完全不同：**不是基于本版
+Story 增量**，而是基于**项目整体当前状态**。
 
 ### 8.1 何时触发
 
-release.sh 完成 changelog/release-notes 写盘后，喂一段以
+发版脚本完成 changelog/release-notes 写盘后，喂一段以
 `## 当前任务：重写 .roll/features.md（Section 8）` 开头的 prompt。
 
 ### 8.2 输入
@@ -420,9 +422,9 @@ prompt 会包含：
   - 该 Feature 下**所有** Story 均为 `📋 Todo` → 在描述末尾追加 `*(规划中)*`
   - 只要有 **≥1 个** `✅ Done` Story → 正常展示，**不加**任何标记
   - 一眼可见：规划中的 Feature 在每个 Epic 分组的末尾列出
-  - **FIX-051 兜底**：`scripts/release.sh` 在 AI 重写后会跑机械校验
+  - **FIX-051 兜底**：发版脚本在 AI 重写后会跑机械校验
     `_enforce_planning_markers`，即使本规则被 AI 漏掉也会自动补 `*(规划中)*`；
-    规则的权威实现是 release.sh 里的纯 shell 函数，prompt 这条只是软提示
+    规则的权威实现是发版脚本里的纯 shell 函数，prompt 这条只是软提示
 - 描述写 1 句话 **产品视角**：用户能用它做什么，避免实现细节
 - **语言：单一中文**。Feature 名（如 `roll-loop` / `Cross-Agent Peer Review`）和命令、环境变量等术语保留英文原样；描述句一律中文。**不要**在条目下追加英文翻译行（早期 v517.x 双语混排版式已废弃，理由：扫读困难、维护翻倍、与 `guide/en|zh/` 平行目录约定不一致；英文受众走 site 端 i18n）
 - 分组用 BACKLOG 的 Epic 名，原序，不重排
@@ -435,5 +437,5 @@ prompt 会包含：
 ### 8.5 失败安全
 
 如果 prompt 信息不足（BACKLOG 解析失败等），**不要部分写入** —— 输出原
-文件内容即可。release.sh 会捕获 stdout 后比较：内容未变就不 stage。
+文件内容即可。发版脚本会捕获 stdout 后比较：内容未变就不 stage。
 

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

@@ -137,7 +137,7 @@ Parse .roll/backlog.md for all `### Feature: <name>` groups that contain ≥1
 | REFACTOR-XXX | features.md 功能目录落后于 BACKLOG，N 个已完成功能区未收录，用户无法通过产品目录发现这些功能 — flagged by dream YYYY-MM-DD | 📋 Todo |
 ```
 
-The catalog is auto-updated by `scripts/release.sh` at release time (Section 8 of roll-.changelog). Between releases, this check surfaces the coverage gap so it isn't silently skipped.
+The catalog is auto-updated by the release script (maintainer-private at `roll-meta/ops/release.sh`) at release time (Section 8 of roll-.changelog). Between releases, this check surfaces the coverage gap so it isn't silently skipped.
 
 **REFACTOR entry format for doc findings:**
 

package/skills/roll-deck/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: roll-deck
+license: MIT
+allowed-tools: "Read, Edit, Write, Glob, Grep, Bash(git:*)"
+description: "Generate a bilingual 18-slide deck.md from a topic. Reads the current project (README, AGENTS.md, backlog, features), discusses outline with the user when needed, and writes one file: .roll/slides/<slug>/deck.md. Each slide carries title_en/title_zh + body_en/body_zh + evidence (file:line). HTML rendering is a separate bash step (roll slides build)."
+---
+
+# roll-deck
+
+> Topic in, deck.md out. AI authoring layer of the slide-deck pipeline.
+> 主题进，deck.md 出。幻灯片管线的 AI 创作层。
+
+## Trigger
+
+User invokes `roll-deck` from the CLI:
+
+```
+$roll-deck "Introducing Roll Loop"
+$roll-deck "How TCR keeps us honest"
+```
+
+`roll slides new "<topic>"` shells out to the selected agent with this skill loaded.
+`roll slides new "<topic>"` 会通过所选 agent 加载本 skill。
+
+## When Not to Use
+
+- Rendering an existing `deck.md` to HTML → use `roll slides build <slug>` (bash, no AI).
+- Listing or previewing decks → use `roll slides list` / `roll slides preview <slug>`.
+- Authoring backlog stories → use `$roll-design` / `$roll-idea`.
+
+## Hard Constraints  硬约束
+
+- **You may write exactly one file**: `.roll/slides/<slug>/deck.md`.
+- 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.
+
+## Inputs
+
+- `<topic>`: a free-text topic string (required).
+- `<template>`: template name, default `introduction-v3`.
+- `<slug>`: kebab-case slug derived from the topic by the CLI; you receive it.
+
+## Workflow
+
+### 1. Read the project  阅读项目
+
+Read in this order, skipping files that don't exist:
+
+1. `README.md` — top-level pitch and entry points.
+2. `AGENTS.md` — communication style, conventions, where to look.
+3. `.roll/backlog.md` — recently Done Stories and the top of the Todo queue.
+4. `.roll/features/**/*.md` — feature specs relevant to the topic.
+5. Targeted `Grep` for the topic keywords across the repo (≤ 30 hits).
+
+Stop reading when you have enough to write 18 slides with concrete evidence.
+拿到足够 18 张 slide 的证据就停。
+
+### 2. Outline check  outline 校验
+
+- If the topic is unambiguous and the project gives clear evidence (high confidence), proceed directly.
+- If the topic is vague (multiple valid framings), restate the proposed 18-slide outline in 3–5 lines and ask the user to confirm or adjust before writing. Wait for confirmation.
+- Never ask more than one round of questions — pick the strongest framing and proceed.
+
+### 3. Generate 18 slides  生成 18 张 slide
+
+Default count is `18` (or the count the template prescribes). Each slide MUST contain:
+
+- `title_en` — short English title (≤ 8 words).
+- `title_zh` — short Chinese title (≤ 16 chars).
+- `body_en` — markdown body, concise, ≤ 200 words.
+- `body_zh` — Chinese body, concise, ≤ 200 chars.
+- `evidence` — list of `<path>:<line>` references that ground the claim.
+
+**Grounding threshold**: every 3 consecutive slides MUST contain at least 1 evidence citation. If you cannot ground a slide, label it `⚠️ unverified` in the body and explain why in one line.
+**Grounding 阈值**：每 3 张 slide 至少 1 条 evidence。无法取证时打 `⚠️ unverified` 并一行说明。
+
+Bilingual rule: English and Chinese MUST be on separate lines in the rendered body — never inline on the same line.
+
+### 4. Write deck.md  写文件
+
+Write to `.roll/slides/<slug>/deck.md` with this structure:
+
+```markdown
+---
+template: <template>
+slug: <slug>
+title_en: "<topic in English>"
+title_zh: "<topic in Chinese>"
+total_slides: 18
+created: <YYYY-MM-DD>
+---
+
+## Slide 1
+title_en: "..."
+title_zh: "..."
+body_en: |
+  ...
+body_zh: |
+  ...
+evidence:
+  - README.md:12
+  - .roll/backlog.md:34
+
+## Slide 2
+...
+```
+
+`total_slides` MUST match the number of `## Slide N` blocks. The validator (run by `roll slides build`) will reject mismatches.
+
+### 5. Prompt the user  提示用户
+
+After writing, print a single bilingual block:
+
+```
+deck.md written → .roll/slides/<slug>/deck.md
+deck.md 已写入 → .roll/slides/<slug>/deck.md
+
+Next:  roll slides build <slug>
+下一步：roll slides build <slug>
+```
+
+Do not run `roll slides build` yourself — that is a deliberate human gate.
+
+## Output format expectations
+
+- One file written: `.roll/slides/<slug>/deck.md`.
+- Final agent message ends with the bilingual "Next" hint above.
+- No HTML, no edits to any other file.
+
+## Rules
+
+- Honour the hard constraints above. The CLI will trust you not to scribble outside the deck file.
+- If `.roll/` does not exist, create it first (with `mkdir -p .roll/slides/<slug>`).
+- If the project has no `README.md` or `AGENTS.md`, proceed using what is available and flag affected slides as `⚠️ unverified`.
+- Keep slides terse — this is a deck, not a doc.