@seanyao/roll 3.621.1 → 3.624.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "3.621.1",
+  "version": "3.624.1",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {

package/skills/README.md

@@ -1,64 +0,0 @@
-# roll-skills
-
-The **skill contracts** for [roll](https://github.com/seanyao/roll) — markdown
-playbooks that AI agents (Claude, Cursor, Kimi, Pi, …) load and follow when
-they work inside a roll-managed project. This repo is mounted into the main
-repo as the `skills/` git submodule and ships inside the
-[`@seanyao/roll`](https://www.npmjs.com/package/@seanyao/roll) npm package;
-`roll setup` syncs the contracts into each installed AI client.
-
-roll 的**技能契约**仓——AI agent 在 roll 项目里工作时加载并遵循的 markdown
-工作流手册。以 `skills/` 子模块挂载进主仓、随 npm 包发布，`roll setup`
-负责同步到各 AI 客户端。
-
-## Skills · 技能清单
-
-**Delivery · 交付主链**
-- `roll-design` — 讨论/设计/拆卡入口（DDD 建模 + INVEST 拆分落 backlog）
-- `roll-build` — 万能交付：US 卡经 TCR 全流程（含验证门与验收证据）
-- `roll-fix` — 缺陷修复轻量链路（FIX 卡专用）
-- `roll-idea` — 一句话快速捕获 → 自动分类编号落 backlog
-- `roll-loop` — 无人值守 BACKLOG 执行器的工作流契约
-
-**Quality · 质量与评审**
-- `roll-peer` — 跨 agent 协商评审（三态协议 + 时间盒）
-- `roll-review-pr` — PR 评审，输出 APPROVE / REQUEST_CHANGES / UNCERTAIN
-- `roll-spar` — 攻防 TDD（高危逻辑双 agent 对抗）
-- `roll-.review` / `roll-.qa` — TCR 内嵌自审与测试金字塔基准
-
-**Observation · 观察与汇报**
-- `roll-notes` — 项目日记
-- `roll-.dream` — 夜间架构/文档健康扫描
-- `roll-doctor` — 工具链体检；`roll-doc-audit` — 文档/产品一致性审计与存量文档自动化
-
-**Lifecycle & misc · 生命周期与杂项**
-- `roll-onboard` — 存量项目交互式接入
-- `roll-propose` — 产品视角提案生成（只进 proposals，不直写 backlog）
-- `roll-.changelog` — Done 卡 → 用户 changelog（含验收证据 marker 约定）
-- `roll-debug` — 网页黑盒诊断探针
-- `roll-.clarify` / `roll-.echo` — 模糊输入的被动澄清
-
-> Each skill's full contract lives in `<skill>/SKILL.md`. Dot-prefixed skills
-> (`roll-.x`) are passive/auto-triggered. 每个技能的完整契约在各自的
-> `SKILL.md`；带点前缀的为被动技能，自动触发。
-
-## Editing · 修改约定
-
-Skills are prose contracts — edit the markdown, PR to `main`, then bump the
-`skills/` submodule pointer in the main repo. Conventions (bilingual output,
-backlog write-back rules, evidence chain) are defined by the main repo's
-AGENTS.md and enforced there.
-
-## Health & Authoring · 健康检查与编写纪律
-
-Skill descriptions are model-facing routing triggers, not human summaries. New
-or edited skills must keep a compact `Load when...` description, positive and
-negative route cases, Roll-specific gotchas, and progressive disclosure through
-`references/`, `assets/`, or `scripts/` when the hub grows.
-
-```bash
-node scripts/audit-skills.mjs --strict
-node scripts/test-audit-skills.mjs
-```
-
-See [docs/skill-authoring.md](docs/skill-authoring.md) for the full rules.

package/skills/docs/skill-authoring.md

@@ -1,74 +0,0 @@
-# Skill Authoring Guide
-
-Roll skills are context that an agent must carry. Keep every skill small,
-routable, and backed by evidence.
-
-## Required Shape
-
-- `SKILL.md` is the hub. Keep trigger boundaries, hard gates, and the shortest
-  execution skeleton in the hub.
-- `description` is a model-facing routing trigger. Start with `Load when...`,
-  keep it at 50 words or fewer, and describe user intent rather than workflow
-  internals.
-- Put heavy examples, long templates, recovery branches, rubrics, and optional
-  runbooks in `references/`.
-- Put reusable generated files, snippets, images, or browser probes in
-  `assets/`.
-- Put deterministic repeated logic in `scripts/` so the agent does not
-  reconstruct boilerplate in context.
-- If a hub must stay over 250 lines, add a reviewed waiver in the hub and
-  explain why splitting would be riskier.
-
-## Route Evidence
-
-Every skill must have route cases in `route-cases/skills.json`:
-
-- At least two positive user intents that should load the skill.
-- At least two negative or forbidden-load intents that should not load the
-  skill.
-- Adjacent skills need explicit negative coverage. Examples:
-  `roll-build` vs `roll-design` vs `roll-fix`,
-  `roll-loop` vs `roll-.dream` vs `roll-sentinel`,
-  `roll-.review` vs `roll-review-pr` vs `roll-peer` vs `roll-spar`.
-
-Changing a description requires updating the route cases in the same change.
-
-## Gotchas
-
-Every hub must include `## Gotchas` or `## Known Failure Modes`.
-
-- Add Roll-specific mistakes, invariants, trigger boundaries, or failure modes.
-- Do not repeat generic coding advice.
-- If a gotcha comes from a missed load, add a positive route case.
-- If a gotcha comes from an off-target load, add a negative route case.
-- Treat the section as append-mostly unless an entry is proven obsolete.
-- Never instruct agents to source the `roll` binary as if it were a shell
-  library: the TS-native `roll` is a bundled CLI, not a bash script, and
-  `source "$(command -v roll)"` executes JS as shell (FIX-274). Skill steps call
-  `roll <command>` directly.
-- Skills do NOT self-score (FIX-343). The working agent never scores its own
-  story; the Review Score is a runner-side peer-review outcome, produced by a
-  Reviewer in a FRESH, separate session (never a sub-agent of the builder's
-  session). Do not author any `self-score` step into a skill.
-
-## Maintenance Workflow
-
-- Description change -> update route cases.
-- Observed skill failure -> add gotcha and route evidence.
-- Heavy new section -> move it to `references/` or `assets/`.
-- Repeatable deterministic command sequence -> move it to `scripts/`.
-- New auxiliary file -> link it from `SKILL.md`; unreferenced spokes fail audit.
-
-## Audit Commands
-
-Run these from the roll-skills repository root:
-
-```bash
-node scripts/audit-skills.mjs
-node scripts/audit-skills.mjs --json
-node scripts/audit-skills.mjs --strict
-node scripts/test-audit-skills.mjs
-```
-
-`--strict` is the gate for description style, route coverage, gotcha coverage,
-hub size, missing spoke references, and unreferenced spoke files.

package/skills/reports/skill-audit-summary.md

@@ -1,53 +0,0 @@
-# Skill Ecosystem Audit Summary
-
-Generated for US-SKILL-023 through US-SKILL-028.
-
-## Strict Audit Result
-
-Command:
-
-```bash
-node scripts/audit-skills.mjs --strict
-```
-
-Result:
-
-- Skills scanned: 23
-- Load-trigger descriptions: 23/23
-- Gotchas coverage: 23/23
-- Skills over 250 lines: 0
-- Skills with auxiliary files: 13
-- Route fixture coverage: 2 positive and 2 negative cases for every skill
-- Violations: 0
-
-## Hub Size Reduction
-
-The initial `SKILL.md` line baseline was 7,929 lines. Current hub-only
-`SKILL.md` total is 1,985 lines. Detailed contracts were moved into
-`references/full-contract.md` for the refactored skills.
-
-| Skill | Baseline hub lines | Current hub lines | Moved content |
-|---|---:|---:|---|
-| roll-design | 924 | 49 | `references/full-contract.md`, `references/engineering-checklist.md` |
-| roll-build | 884 | 48 | `references/full-contract.md` |
-| roll-fix | 641 | 48 | `references/full-contract.md` |
-| roll-debug | 607 | 48 | `references/full-contract.md`, `assets/injectable-bb.js` |
-| roll-doc-audit | 595 | 46 | `references/full-contract.md` |
-| roll-loop | 563 | 47 | `references/full-contract.md` |
-| roll-.changelog | 465 | 47 | `references/full-contract.md` |
-| roll-.dream | 374 | 47 | `references/full-contract.md` |
-| roll-sentinel | 364 | 46 | `references/full-contract.md` |
-| roll-peer | 336 | 47 | `references/full-contract.md` |
-| roll-deck | 296 | 46 | `references/full-contract.md` |
-| roll-spar | 289 | 47 | `references/full-contract.md` |
-| roll-.qa | 258 | 47 | `references/full-contract.md` |
-
-## Maintenance Rules Added
-
-- Descriptions start with `Load when...` and route on user intent.
-- `route-cases/skills.json` carries positive and negative route examples.
-- Every hub has `Gotchas` with Roll-specific failure modes.
-- Long contracts load progressively through `references/`, `assets/`, or
-  `scripts/`.
-- `scripts/audit-skills.mjs --strict` gates description style, route coverage,
-  gotcha coverage, hub size, and spoke integrity.

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

@@ -1,47 +0,0 @@
----
-hidden: true
-name: roll-.changelog
-license: MIT
-allowed-tools: "Read, Edit, Write, Bash(git:*)"
-description: "Load when a completed Roll build or deploy needs CHANGELOG.md generated or updated from Done stories, acceptance evidence, and release notes."
----
-# Roll Changelog
-
-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 completed Roll build or deploy needs CHANGELOG.md generated or updated from Done stories, acceptance evidence, and release notes.
-
-## When Not to Use
-
-- Planning new backlog stories.
-- Owner internal briefing; load roll-brief.
-
-## 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. Read Done stories and acceptance evidence.
-2. Generate or update CHANGELOG.md.
-3. Keep user-facing language external and concise.
-4. Stage only the changelog artifact when required.
-
-## Hard Gates
-
-- No changelog entries from unaccepted work.
-- No private backlog/process detail in public notes.
-
-## Gotchas
-
-- Only run after completion/deploy evidence exists; do not invent changelog bullets from Todo or In Progress backlog rows.
-- Keep internal backlog detail out of user-facing CHANGELOG.md unless it is part of accepted release evidence.
-
-## 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.