@seanyao/roll 3.618.3 → 3.620.1

package/skills/roll-loop/references/full-contract.md

@@ -89,7 +89,7 @@ loop:
 ### Step 1 — Orphan 🔨 Recovery
 
 Process-level crash recovery (LOCK, heartbeat, retry budget) is handled by
-the runner in `bin/roll:_write_loop_runner_script` — the per-project LOCK
+the v3 runner (`packages/cli/src/runner/run-cycle.ts`) — the per-project LOCK
 guarantees only one cycle for this slug is alive when you start. So at
 this point, any `🔨 In Progress` row in `.roll/backlog.md` belongs to a
 previous cycle that crashed before flipping it back; reclaim it before
@@ -132,27 +132,27 @@ Before scanning BACKLOG, process open PRs first. PRs are also units of work:
 external contributors and human teammates expect their PRs to be reviewed and
 moved forward, not starved while loop opens new fronts.
 
-Call `_loop_pr_inbox` after the pre-run CI check passes. It walks
+Call `roll loop pr-inbox` after the pre-run CI check passes. It walks
 `gh pr list --state open` and routes each PR by classification:
 
 | Classification | Action |
 |---|---|
-| `loop_self` (head ref starts with `loop/` **or** `claude/`, CI not red) | `_loop_pr_merge_self_eager` — squash-merge directly when CI green + clean; if the PR is BEHIND/CONFLICTING with main, `_loop_pr_rebase_stale` rebases it first (circuit-gated) so it merges on a later tick. Never AI-review your own commit. (Agent-authored `claude/*` PRs are loop-owned the same way; a CI-red `claude/*` PR is **not** auto-healed — it falls through for a human to decide.) |
-| `loop_self_ci_red` (loop/* PR whose CI went red) | **US-LOOP-062a**: `_loop_pr_heal_self` — background-heal (per-PR lock + heal budget `ROLL_LOOP_HEAL_MAX`, default 2, via `_project_agent`); on `ROLL_LOOP_NO_HEAL=1` / budget exhausted → deduped `[TYPE:loop-pr-ci-red]` ALERT (never silently dropped) |
+| `loop_self` (head ref starts with `loop/` **or** `claude/`, CI not red) | squash-merge directly when CI green + clean; if the PR is BEHIND/CONFLICTING with main, rebase it first (circuit-gated) so it merges on a later tick. Never AI-review your own commit. (Agent-authored `claude/*` PRs are loop-owned the same way; a CI-red `claude/*` PR is **not** auto-healed — it falls through for a human to decide.) |
+| `loop_self_ci_red` (loop/* PR whose CI went red) | **US-LOOP-062a**: background-heal via `roll loop pr-heal-run` (per-PR lock + heal budget `ROLL_LOOP_HEAL_MAX`, default 2, via the configured agent); on `ROLL_LOOP_NO_HEAL=1` / budget exhausted → deduped `[TYPE:loop-pr-ci-red]` ALERT (never silently dropped) |
 | `blocked_human_request_changes` | Skip — last human review requested changes; wait for the author to push fixes |
-| `blocked_human_approved` | **US-LOOP-062b**: `_loop_pr_merge_approved` — merge directly (`gh pr merge --squash`) when CI green + mergeable, instead of relying on repo auto-merge (which may be off); merge failure is non-fatal (retried next tick) |
-| `stale` (CI failed or branch behind/conflicting) | Try `_loop_pr_rebase_stale` after the circuit breaker allows it |
-| `eligible` (clean external PR, no blocking review) | Invoke `_loop_pr_review_external` — the actual decision is provided by US-AUTO-035's GitHub Action |
+| `blocked_human_approved` | **US-LOOP-062b**: merge directly (`gh pr merge --squash`) when CI green + mergeable, instead of relying on repo auto-merge (which may be off); merge failure is non-fatal (retried next tick) |
+| `stale` (CI failed or branch behind/conflicting) | Rebase onto `origin/main` after the circuit breaker allows it |
+| `eligible` (clean external PR, no blocking review) | Review via `roll review-pr` (or the equivalent project agent skill) — the actual decision is provided by US-AUTO-035's GitHub Action |
 
-**Rebase circuit breaker** — `_loop_pr_rebase_circuit <pr>` records each rebase
-attempt under `pr_state.<PR>.attempts_at` in the per-slug state file
+**Rebase circuit breaker** — the runner records each rebase attempt under
+`pr_state.<PR>.attempts_at` in the per-slug state file
 (`~/.shared/roll/loop/state-<slug>.yaml`, FIX-052), pruning entries older
 than 24 h. Once ≥3 attempts land within 24 h, further rebases are blocked and an
 ALERT is written (typical cause: a broken workflow file makes CI never run,
 which would otherwise drive infinite rebase loops).
 
 **Lenient on infrastructure** — `gh` missing, repo unparseable, or any
-`gh` API failure → `_loop_pr_inbox` returns 0 and the loop falls through to
+`gh` API failure → `roll loop pr-inbox` returns 0 and the loop falls through to
 Step 2 (BACKLOG scan). Same posture as the pre-run CI check.
 
 ### Step 2 — Scan BACKLOG
@@ -172,27 +172,19 @@ claimed by an **open `loop/*` PR**. Each cycle's worktree is branched from
 locally until that cycle's PR merges. Without this gate, two cycles started
 back-to-back will both pick the same Todo row and produce duplicate PRs.
 
-```bash
-bash -c 'source "$(command -v roll)"; _loop_pr_claimed_stories'
-#   stdout: one story ID per line (deduped) — these are claimed by open
-#           loop/* PRs on the remote. SKIP any candidate whose ID appears.
-#   exit 0 always (lenient: gh missing / API error → empty output).
-```
+Use `roll loop pr-inbox` to discover story IDs already claimed by open
+`loop/*` PRs on the remote. Skip any candidate whose ID appears. The runner is
+lenient: `gh` missing / API error → empty claim list.
 
-**Dependency gate** (FIX-032). For each `📋 Todo` candidate, before picking:
-
-```bash
-# Source bin/roll once per cycle, then call the helper per candidate.
-source "$(command -v roll)"
-
-bash -c 'source "$(command -v roll)"; _loop_check_depends_on "<story-id>" .roll/backlog.md'
-#   exit 0 → all `depends-on:US-X,US-Y` are ✅ Done → eligible
-#   exit 1 → stdout lists unsatisfied dep IDs; SKIP this story, log to
-#            runs.jsonl `skipped` with reason "depends-on: <unsatisfied>"
-```
+**Dependency gate** (FIX-032). For each `📋 Todo` candidate, before picking,
+check that every `depends-on:<ID>` referenced in the story's backlog row is
+already ✅ Done. The v3 runner evaluates dependencies natively; do not call the
+retired bash helper `_loop_check_depends_on`. If a dependency is unsatisfied,
+skip the story and log to `runs.jsonl` `skipped` with reason
+`"depends-on: <unsatisfied>"`.
 
 Move to the next candidate when skipping. The gate is a pure function
-over .roll/backlog.md text — no side effects, no LOCK interaction.
+over `.roll/backlog.md` text — no side effects, no LOCK interaction.
 
 Cap at `max_items_per_run` to limit blast radius per cycle.
 
@@ -200,7 +192,7 @@ Cap at `max_items_per_run` to limit blast radius per cycle.
 
 Loop has two layers of concurrency protection:
 
-1. **Per-project LOCK** (enforced by runner script, see `bin/roll:_write_loop_runner_script`):
+1. **Per-project LOCK** (enforced by the v3 runner, see `packages/cli/src/runner/run-cycle.ts`):
    - LOCK file path: `~/.shared/roll/loop/.LOCK-<project-slug>`
    - On launch: if LOCK exists and the PID inside is alive → exit 0 (previous loop still running)
    - On launch: if LOCK exists but PID is dead → clean up stale LOCK and continue
@@ -219,42 +211,30 @@ Together these mean: only one loop runs at a time per project (LOCK), and within
 
 > **US-AGENT-006 — Per-story agent routing (pre-cycle)**
 >
-> Before this skill even starts, the runner inner script has already:
-> 1. Picked the next eligible Todo via `_loop_pick_next_story` (priority FIX > US > REFACTOR, depends-on gate respected)
-> 2. Read its Agent profile (est_min / risk_zone) and routed an agent via `_loop_pick_agent_for_story` (hard rules from `.roll/agent-routes.yaml` + soft preference from `runs.jsonl`)
-> 3. Exported `ROLL_LOOP_ROUTED_STORY` / `ROLL_LOOP_ROUTED_AGENT` / `ROLL_LOOP_ROUTED_RULE` and printed `[loop] story <id> routed to <agent> via <rule_kind>` to cron.log
+> Before this skill even starts, the v3 runner has already:
+> 1. Picked the next eligible Todo (priority FIX > US > REFACTOR, depends-on gate respected).
+> 2. Read its Agent profile (`est_min` / `risk_zone`) and routed an agent (hard rules from `.roll/agent-routes.yaml` + soft preference from `runs.jsonl`).
+> 3. Exported `ROLL_LOOP_ROUTED_STORY` / `ROLL_LOOP_ROUTED_AGENT` / `ROLL_LOOP_ROUTED_RULE` and printed `[loop] story <id> routed to <agent> via <rule_kind>` to cron.log.
 >
-> When `ROLL_LOOP_ROUTED_STORY` is set, prefer it as `US_ID` for this cycle. The story has already been chosen by hard+soft routing rules — and, per FIX-146, the runner re-validates it against the authoritative backlog right before handing it to you (re-picking the next eligible Todo if it went ✅ Done / In Progress / ineligible between pick and handoff, emitting a `story_stale` event). So treat `ROLL_LOOP_ROUTED_STORY` as already-eligible and just work it. Only if you still find at cycle start that it is no longer 📋 Todo in BACKLOG (a residual concurrent flip), re-pick the next eligible Todo via `_loop_pick_next_story` rather than idling the whole cycle.
+> When `ROLL_LOOP_ROUTED_STORY` is set, prefer it as `US_ID` for this cycle. The story has already been chosen by hard+soft routing rules — and, per FIX-146, the runner re-validates it against the authoritative backlog right before handing it to you (re-picking the next eligible Todo if it went ✅ Done / In Progress / ineligible between pick and handoff, emitting a `story_stale` event). So treat `ROLL_LOOP_ROUTED_STORY` as already-eligible and just work it. Only if you still find at cycle start that it is no longer 📋 Todo in BACKLOG (a residual concurrent flip), signal `story_stale` and let the runner pick the next eligible Todo rather than idling the whole cycle.
 >
 > Old single-agent fallback (`primary_agent` from `~/.roll/config.yaml`) still applies when:
 > - no story is pickable (empty Todo / all blocked by depends-on)
 > - the matching agent-routes.yaml has no agent that fits the story profile (then `cold_start_default` is used)
 
-For each item, **before invoking the executor skill**, mark the story 🔨 In Progress in the **main repo's** .roll/backlog.md so brief and peer agents can see it being worked on. The cycle worktree is gitignored at .roll/, so editing the worktree's own copy + committing carries no change back to main — write directly via the helper instead:
-
-```bash
-bash -c 'source "$(command -v roll)"; _loop_mark_in_progress US-XXX'
-# Updates ${ROLL_MAIN_PROJECT}/.roll/backlog.md in place: flips the row
-# containing US-XXX from "📋 Todo" to "🔨 In Progress". Idempotent.
-```
+For each item, **before invoking the executor skill**, mark the story 🔨 In Progress in the **main repo's** `.roll/backlog.md` so brief and peer agents can see it being worked on. The cycle worktree is gitignored at `.roll/`, so editing the worktree's own copy + committing carries no change back to main — write directly via the backlog store instead. The v3 runner updates `${ROLL_MAIN_PROJECT}/.roll/backlog.md` in place; do not call the retired bash helpers `_loop_mark_in_progress` / `_loop_mark_todo`.
 
-If the executor fails (TCR aborts, CI red, etc.), revert the marker so the next cycle can re-pick the story:
+If the executor fails (TCR aborts, CI red, etc.), revert the marker so the next cycle can re-pick the story.
 
-```bash
-bash -c 'source "$(command -v roll)"; _loop_mark_todo US-XXX'
-```
+Status flips happen in main directly — no per-cycle commit needed. `roll-brief` reads main's backlog, so the 🔨 marker is visible the moment the update returns.
 
-Status flips happen in main directly — no per-cycle commit needed. `roll-brief` reads main's backlog, so the 🔨 marker is visible the moment the helper returns.
+选定故事后，发出 `pick_todo` 事件，让 dashboard / monitor / attach 都能把"这个 cycle 选了哪个 story"正确归类。 The v3 runner emits events natively; do not call the retired bash helper `_loop_event`.
 
-选定故事后，调用 `_loop_event` 发出 pick_todo 事件，让 dashboard / monitor / attach 都能把"这个 cycle 选了哪个 story"正确归类：
-
-```bash
-# 选定故事后立即 emit（在调用 executor skill 之前）
-# label 必须是 cycle_id（来自 bin/roll 注入的 LOOP_CYCLE_ID 环境变量），
-# 不是 US_ID — dashboard 按 label 聚类，US_ID 当 label 会让事件分到错的桶
-# 里，cycle 看起来"有 token 没 ID"。
-_loop_event pick_todo "$LOOP_CYCLE_ID" "$US_ID" ""
-```
+- Emit immediately after picking and before invoking the executor skill.
+- `label` must be the `cycle_id` (from the `LOOP_CYCLE_ID` environment variable),
+  not `US_ID` — the dashboard groups by label, and using `US_ID` as the label
+  would put events in the wrong bucket, making the cycle appear to have tokens
+  but no ID.
 
 Then invoke the executor:
 
@@ -287,8 +267,8 @@ After each item completes:
    - Count `tcr:` prefix commits since `started_at` via `git log --oneline --since=<started_at>`
    - Count == 0 → revert story status in .roll/backlog.md from ✅ Done → 📋 Todo; write ALERT to `~/.shared/roll/loop/ALERT-<slug>.md` with story ID, time, reason "zero tcr: commits since story start", and suggested actions (`roll loop now` / `$roll-build <id>` / `roll loop reset`)
    - Count > 0 → continue normally
-2. **CI Gate** — **MUST** invoke `roll ci --wait` (the `_loop_enforce_ci`
-   wrapper). **Do NOT call `gh` directly** (no `gh run list`, no `gh run watch`,
+2. **CI Gate** — **MUST** invoke `roll ci --wait`. **Do NOT call `gh` directly**
+   (no `gh run list`, no `gh run watch`,
    no ad-hoc shell checks): `roll ci --wait` is the only sanctioned entry —
    it derives `owner/repo` from the git remote and uses `gh -R <slug>`, which
    is required to work through `~/.ssh/config` host rewrites that break gh's
@@ -327,7 +307,7 @@ After each item completes:
       merges / rebases / closes it asynchronously. There is no false-Done risk:
       with worktree isolation the ✅ Done lives only in the unmerged PR, never on
       the loop's main checkout, and the story is not re-picked meanwhile via the
-      open-PR eligibility gate (`_loop_story_is_eligible`, FIX-146). The story's
+      open-PR eligibility gate (FIX-146). The story's
       ✅ Done lands on main only when the PR Loop actually merges the PR.
    2. Write ALERT to `~/.shared/roll/loop/ALERT-<slug>.md` with:
       - story ID, time, commit SHA
@@ -346,10 +326,9 @@ After each item completes:
 
 ### Step 5 — Write Run Summary
 
-> **FIX-044**: The inner runner script (`_write_loop_runner_script` in `bin/roll`)
-> now appends this record deterministically at cycle end. The shell write is the
-> authoritative record; the agent should still emit a run summary in the cycle's
-> final report for `cron.log` visibility.
+> **FIX-044**: The v3 runner (`packages/cli/src/runner/run-cycle.ts`) appends
+> this record deterministically at cycle end. The agent should still emit a run
+> summary in the cycle's final report for `cron.log` visibility.
 
 After all items in this cycle:
 

package/skills/roll-onboard/SKILL.md

@@ -29,7 +29,7 @@ You are the **认知 (cognition) layer**. Your job ends with writing a plan file
 | You do | You do NOT |
 |--------|------------|
 | Read project code, infer type/domains/modules | Modify any source file |
-| Call `roll-doc --dry-run` to get a gap report | Call `roll-doc` (write mode) |
+| Call `roll-doc-audit --dry-run` to get a gap report | Call `roll-doc-audit` (write mode) |
 | Ask the user 9 questions across 3 groups | Decide for the user |
 | Produce `.roll/onboard-plan.yaml` | Write `.gitignore` |
 | Produce `.roll/onboard-plan.yaml` | Run `roll init --apply` |
@@ -40,7 +40,7 @@ Hard constraint: **AI cannot create files in the user's project other than `.rol
 
 1. The repository tree (use the project's own structure to infer technologies)
 2. Any existing `README.md` / `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` etc. as evidence
-3. `roll-doc --dry-run` output → identifies what documentation gaps exist
+3. `roll-doc-audit --dry-run` output → identifies what documentation gaps exist
 4. The path-audit pattern: scan for legacy structure markers (`BACKLOG.md`, `docs/features/`, etc.) — if any are present, REFUSE and tell the user to run `npx @seanyao/roll@2 migrate` first
 
 ## Workflow
@@ -113,7 +113,7 @@ Map the findings into the three buckets:
 
 ### Step 2 — Get gap report
 
-Run `roll-doc --dry-run` (READ-ONLY mode). This reports:
+Run `roll-doc-audit --dry-run` (READ-ONLY mode). This reports:
 - Which standard Roll artifacts (BACKLOG, features, domain models) are missing
 - Which existing docs Roll could `include` rather than regenerate
 

package/skills/roll-peer/references/full-contract.md

@@ -58,13 +58,7 @@ Allowed states only. No invented words.
 - **OBJECT**: The proposal is wrong. Provide an alternative. Proceed to next round.
 - **ESCALATE**: Round 3 reached without AGREE, or a round fails due to API/token error. Hand off to the human user.
 
-After each round decision, emit a `peer` event to the cycle event stream:
-
-```bash
-# $round = current round number, $total = max rounds, $verdict = AGREE/REFINE/OBJECT/ESCALATE
-# $agents = e.g. "claude→deepseek"
-_loop_event peer "${round}/${total}" "$verdict" "$agents" 2>/dev/null || true
-```
+After each round decision, emit a `peer` event to the cycle event stream. The v3 runner writes events natively; do not call the retired bash helper `_loop_event`.
 
 If information is insufficient:
 ```

package/skills/route-cases/skills.json

@@ -61,16 +61,6 @@
         "ask another agent for peer negotiation"
       ]
     },
-    "roll-brief": {
-      "positive": [
-        "prepare an owner-facing digest of completed and in-progress Roll work",
-        "summarize backlog queue, escalations, and release readiness"
-      ],
-      "negative": [
-        "write public release notes for users",
-        "capture a one-line idea into backlog"
-      ]
-    },
     "roll-build": {
       "positive": [
         "execute US-AUTH-001 through TCR and verification",
@@ -111,8 +101,9 @@
         "hotfix a specific BUG-XXX item"
       ]
     },
-    "roll-doc": {
+    "roll-doc-audit": {
       "positive": [
+        "check README guide site and CLI help against implemented behavior",
         "scan docs and generate docs/INDEX.md",
         "find undocumented modules and draft missing documentation"
       ],
@@ -211,16 +202,6 @@
         "run attacker and defender agents for high-risk logic"
       ]
     },
-    "roll-sentinel": {
-      "positive": [
-        "sample production behavior against backlog requirements",
-        "run cost-controlled patrol checks on deployed flows"
-      ],
-      "negative": [
-        "scan code architecture for refactor candidates",
-        "debug a local browser page with console capture"
-      ]
-    },
     "roll-spar": {
       "positive": [
         "use adversarial TDD for auth or payment logic",

package/skills/roll-brief/SKILL.md

@@ -1,207 +0,0 @@
----
-name: roll-brief
-license: MIT
-allowed-tools: "Read, Glob, Grep, Write, Bash(git:*)"
-description: "Load when the owner asks for an internal Roll briefing summarizing completed work, in-progress items, backlog queue, escalations, and release readiness."
----
-# Roll Brief
-
-## Gotchas
-
-- Brief is owner-facing internal context, not public changelog copy.
-- Call out escalations and release readiness explicitly; do not flatten them into a generic progress summary.
-
-> Follows the Architecture Constraints, Development Discipline, and Engineering
-> Common Sense defined in the project AGENTS.md.
-
-Owner-facing digest of autonomous agent activity. Gives the human everything
-needed to decide whether to cut a new release — without having to read every
-commit or diff.
-
-## Distinct from roll-.changelog
-
-| | roll-brief | roll-.changelog |
-|--|-----------|----------------|
-| **Audience** | Product owner (internal) | End users (public) |
-| **Content** | All activity including REFACTOR, escalations, health signals | Only user-visible feature changes |
-| **Trigger** | Feature completion / daily / on-demand | Post-deploy |
-| **Tone** | Operational, candid | Product-facing, polished |
-
-## Trigger Modes
-
-### 1. Feature Completion (auto)
-
-Triggered by `roll-loop` when a set of related Stories under one Feature are
-all marked ✅ Done. The loop passes the Feature name as context.
-
-### 2. Daily Morning (scheduled)
-
-Runs at a fixed time each morning (configurable in `~/.roll/config.yaml`).
-Covers all activity since the previous brief.
-
-```yaml
-# ~/.roll/config.yaml
-brief:
-  daily_time: "08:00"   # local time
-  timezone: "Asia/Shanghai"
-```
-
-### 3. On-Demand
-
-```bash
-$roll-brief                    # since last brief
-$roll-brief --since 2026-05-09 # since specific date
-$roll-brief --feature auth     # scoped to one feature
-```
-
-## Workflow
-
-### Step 1 — Determine Scope
-
-```bash
-# Find timestamp of last brief
-ls .roll/briefs/ | sort | tail -1
-
-# 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 .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 `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
-
-A simple heuristic — not a gate, just a signal for the human:
-
-```
-✅ Release candidate if:
-  - No 🔨 in-progress US items
-  - No open ESCALATE alerts
-  - CI is green (check latest workflow run)
-  - No critical REFACTOR entries flagged in last 48h
-
-⚠️  Hold if any of the above is false
-```
-
-### Step 4 — Write Brief
-
-文件命名：`.roll/briefs/YYYY-MM-DD-{NN}.md`，NN 为当日序号（01 起，零填充两位）。
-计算方式：`ls .roll/briefs/YYYY-MM-DD-*.md 2>/dev/null | wc -l`，+1 即为本次序号。
-
-全部用中文输出。**省略空 section**（无内容时连标题一起不输出）：
-
-```markdown
-# 简报 {YYYY-MM-DD HH:mm}
-
-> 触发：{触发原因} | 覆盖：{起止时间范围}
-
-## 已完成（{N} 项）
-| 编号 | 描述 | 类型 |
-|----|-------------|------|
-| US-XXX | {标题} | 用户故事 |
-| FIX-XXX | {标题} | 缺陷修复 |
-| REFACTOR-XXX | {标题} | 重构 |
-
-<!-- 仅当有 🔨 条目时输出 -->
-## 进行中
-| 编号 | 描述 |
-|----|-------------|
-| US-XXX | {标题} — 开始于 {date} |
-
-<!-- 仅当有 📋 条目时输出 -->
-## 待处理队列（{N} 项）
-| 编号 | 描述 | 优先级 |
-|----|-------------|----------|
-| US-XXX | {标题} | 高 |
-
-<!-- US-AGENT-010: per-agent hit-rate summary (one line). Read the last
-     window_cycles records of runs.jsonl, group by `agent`, format as
-     `agents: pi 8/22 (36%) · deepseek 5/8 (63%)`. Sample < 5 → `(n/a)`.
-     Omit when no records have an agent field (legacy data). -->
-## Agent 路由命中率
-{agents: <name> built/total (pct%) · …}  ← from `runs.jsonl` last 50 cycles
-
-<!-- 仅当 roll-.dream 有新发现时输出 -->
-## 悟见
-{来自 .roll/dream/ 的摘要}
-
-<!-- 仅当有 ESCALATE 告警时输出 -->
-## 需人工介入
-{告警内容}
-
-<!-- 始终输出 doc coverage 数字；若无缺口写"覆盖完整" -->
-## 文档覆盖度
-- guide/en: {N} 个文档
-- ZH 翻译率：{M}/{N}（{%}）
-- {缺口列表 或 "覆盖完整，无缺口。"}
-
-## 发版就绪
-{✅ 可发版 / ⚠️ 暂缓 — 原因}
-
-**下一版本：** `v{YYYY}.{MMDD}.{序号}`
-
-- {本轮新增 1}
-- {本轮新增 2}
-
----
-*状态：进行中 {N} · 待处理 {N} · 告警 {N} | 下次简报：{datetime}*
-```
-
-**首份简报或传入 `--full-history`**：在"已完成"表格后追加历史汇总区块：
-
-```markdown
-### 历史汇总
-**Epic: {Name}** — {done}/{total} ✅
-```
-
-### Step 4.5 — Commit Brief
-
-写完文件后立即提交，让简报进入 git 历史，便于后续追溯与跨会话审计：
-
-```bash
-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；保持工作区干净，由调用方处理重试
-- 仅 `.roll/briefs/` 下新文件入 commit，不要顺带带入其他无关变更
-
-### Step 5 — Notify
-
-写完文件后在终端或 CI 日志中打印简报路径：
-
-```
-📋 $(msg brief.generated ".roll/briefs/YYYY-MM-DD-NN.md")
-   $(msg brief.release_readiness): ✅ $(msg brief.release_ready_status)
-```
-
-有升级事项时须显著打印，不得遗漏。
-
-## Scheduler Configuration
-
-roll-brief runs **locally**, triggered either by roll-loop (on Feature
-completion) or by local cron (daily morning). The agent reads local
-BACKLOG state and git history directly.
-
-### Local cron (daily morning)
-
-Installed automatically via `roll loop on` alongside roll-loop and roll-.dream.
-The cron entry is generated using the configured agent — no manual cron editing needed.
-
-### Triggered by roll-loop
-
-When roll-loop detects a Feature is fully complete, it invokes roll-brief
-automatically — no separate cron entry needed for that trigger.

package/skills/roll-doc/SKILL.md

@@ -1,46 +0,0 @@
----
-name: roll-doc
-license: MIT
-allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(date:*,find:*,stat:*,wc:*)"
-description: "Load when a project needs documentation inventory, docs/INDEX generation, undocumented module detection, or draft documentation fills for existing code."
----
-# Roll Doc
-
-This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.
-
-## Load
-
-Load when a project needs documentation inventory, docs/INDEX generation, undocumented module detection, or draft documentation fills for existing code.
-
-## When Not to Use
-
-- Presentation deck generation; load roll-deck.
-- Toolchain diagnosis; load roll-doctor.
-
-## Read On Demand
-
-- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
-- Keep this hub in context for trigger boundaries and hard gates.
-
-## Workflow Skeleton
-
-1. Scan documentation and code surfaces.
-2. Generate or update docs/INDEX.md.
-3. Identify undocumented modules.
-4. Draft fills from code evidence.
-
-## Hard Gates
-
-- Do not invent behavior without source evidence.
-- Keep docs linked and indexable.
-
-## Gotchas
-
-- Draft missing docs from current code evidence; do not hallucinate module behavior from filenames alone.
-- Documentation inventory is not a product deck or owner brief.
-
-## Maintenance
-
-- Description changes require updates in `route-cases/skills.json`.
-- New observed failures should add a gotcha and the matching positive or negative route case.
-- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.

package/skills/roll-sentinel/SKILL.md

@@ -1,46 +0,0 @@
----
-name: roll-sentinel
-license: MIT
-allowed-tools: "Read, Edit, Write, Bash, WebFetch"
-description: "Load when production or deployed behavior needs cost-controlled randomized patrol checks based on backlog requirements and runtime sampling."
----
-# Roll Sentinel
-
-This hub keeps the routing boundary, hard gates, and execution skeleton in the initial context. Load the heavier runbook only when the task actually needs the detailed contract.
-
-## Load
-
-Load when production or deployed behavior needs cost-controlled randomized patrol checks based on backlog requirements and runtime sampling.
-
-## When Not to Use
-
-- Code health scans; load roll-.dream.
-- Interactive page debugging; load roll-debug.
-
-## Read On Demand
-
-- Read [the full contract](references/full-contract.md) before executing the workflow end to end, recovering from failures, or checking exact output templates.
-- Keep this hub in context for trigger boundaries and hard gates.
-
-## Workflow Skeleton
-
-1. Select sampling targets from backlog requirements.
-2. Run randomized cost-controlled checks.
-3. Validate observed production behavior.
-4. Record patrol evidence and escalate anomalies.
-
-## Hard Gates
-
-- Sampling budget remains explicit.
-- Do not turn sentinel into exhaustive monitoring.
-
-## Gotchas
-
-- Sentinel samples deployed behavior; it is not a code architecture scanner.
-- Keep cost controls and randomized sampling visible; do not turn patrols into exhaustive monitoring.
-
-## Maintenance
-
-- Description changes require updates in `route-cases/skills.json`.
-- New observed failures should add a gotcha and the matching positive or negative route case.
-- Heavy examples, templates, recovery paths, and deterministic snippets belong in `references/`, `assets/`, or `scripts/`, not in this hub.