@seanyao/roll 3.0.0 → 3.606.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "3.0.0",
+  "version": "3.606.1",
   "description": "Roll \u2014 Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {

package/skills/README.md

@@ -0,0 +1,51 @@
+# 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-brief` — owner 简报；`roll-notes` — 项目日记
+- `roll-sentinel` — 生产抽查巡检；`roll-.dream` — 夜间架构/文档健康扫描
+- `roll-doctor` — 工具链体检；`roll-doc` — 存量文档自动化
+
+**Lifecycle & misc · 生命周期与杂项**
+- `roll-onboard` — 存量项目交互式接入
+- `roll-propose` — 产品视角提案生成（只进 proposals，不直写 backlog）
+- `roll-.changelog` — Done 卡 → 用户 changelog（含验收证据 marker 约定）
+- `roll-deck` — 双语 18 页 deck 生成
+- `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.

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

@@ -10,6 +10,19 @@ description: After build completion, extracts completed Stories from .roll/backl
 
 After successful Build & Deploy, extracts completed Stories from .roll/backlog.md to generate a user-friendly `CHANGELOG.md`.
 
+## Evidence marker（US-ATTEST-008 约定）
+
+写入 CHANGELOG 的每个条目，若对应 story 存在验收报告
+（`.roll/verification/<id>/latest/report.html`），在该 bullet 行的下一行追加
+不可见注释 marker（GitHub Release body 不渲染，grep 可追溯）：
+
+```markdown
+- 修复导出报表时间区间偏移（FIX-200）
+  <!-- evidence: .roll/verification/FIX-200/latest/report.html -->
+```
+
+报告不存在则不加（deletion-not-placeholder，与报告渲染同一契约）。
+
 ## When Triggered
 
 - **Auto-triggered**: After successful deploy of `$roll-build` or `$roll-fix`

package/skills/roll-build/SKILL.md

@@ -572,14 +572,34 @@ Follow the repo's deployment path (Vercel / Railway / etc.) and record the deplo
 
 **Hard Rule**: "I confirmed the tests passed" does not count as evidence. Must be **freshly run** command output from this session.
 
+### Phase 10.6: Acceptance Evidence (after Gate PASS)
+
+Runs ONLY on a ✅ Gate PASS (a FAIL retry must not mint a misleading report). Non-blocking: any failure here → WARN, continue to Phase 11.
+
+1. **Dump raw evidence** produced in this session to story-level dirs:
+   `.roll/verification/{ID}/evidence/*.txt` (command outputs, curl, logs) and
+   `.roll/verification/{ID}/screenshots/*.png` (when the story has a UI surface — web/iOS/Android per project type).
+2. **Write the intent map** `.roll/verification/{ID}/ac-map.json` — for EVERY AC (ids `{ID}:AC1..n`) pick `pass|readonly|partial|claimed|missing` and reference only evidence that exists (paths relative to the run dir; story-level dirs are reachable as `../evidence/...` / `../screenshots/...`):
+
+```json
+[{ "ac": "{ID}:AC1", "status": "pass",
+   "evidence": [{ "kind": "text", "label": "vitest", "textFile": "../evidence/vitest.txt" }] }]
+```
+
+   No evidence for an AC → say `claimed` yourself; the renderer enforces that downgrade anyway (red line) and lists it under Discrepancies.
+3. **Run** `roll attest {ID}` (add `--deploy-url <url>` when one exists). The report lands at `.roll/verification/{ID}/latest/report.html`.
+
 ### Phase 11: Write Back Status (REQUIRED)
 
 Both locations must be updated — neither can be skipped:
 
 **① Update .roll/backlog.md index row (Status column):**
 
+**Location rule (FIX-198)**: edit the MAIN project's backlog by ABSOLUTE path — `${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md`. In ordinary projects the cycle worktree has NO `.roll/` (gitignored, never checked out): a relative `.roll/backlog.md` edit writes into the void and the flip silently vanishes.
+
+
 ```markdown
-| [US-{ID}](.roll/features/<feature>.md#us-{id}) | {Title} | ✅ Done |
+| [US-{ID}](.roll/features/<feature>.md#us-{id}) | {Title} | ✅ Done · [evidence](.roll/verification/US-{ID}/latest/report.html) |
 ```
 
 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.

package/skills/roll-fix/SKILL.md

@@ -339,6 +339,23 @@ Verify the shipped fix on the deployed target:
 
 **Hard Rule**: "I confirm tests passed" does not count as evidence. It must be **freshly run** command output from this session.
 
+### 10.6: Acceptance Evidence (after Gate PASS)
+
+Runs ONLY on a ✅ Gate PASS (a FAIL retry must not mint a misleading report). Non-blocking: any failure here → WARN, continue to Step 11.
+
+1. **Dump raw evidence** produced in this session to story-level dirs:
+   `.roll/verification/{ID}/evidence/*.txt` (command outputs, curl, logs) and
+   `.roll/verification/{ID}/screenshots/*.png` (when the story has a UI surface — web/iOS/Android per project type).
+2. **Write the intent map** `.roll/verification/{ID}/ac-map.json` — for EVERY AC (ids `{ID}:AC1..n`) pick `pass|readonly|partial|claimed|missing` and reference only evidence that exists (paths relative to the run dir; story-level dirs are reachable as `../evidence/...` / `../screenshots/...`):
+
+```json
+[{ "ac": "{ID}:AC1", "status": "pass",
+   "evidence": [{ "kind": "text", "label": "vitest", "textFile": "../evidence/vitest.txt" }] }]
+```
+
+   No evidence for an AC → say `claimed` yourself; the renderer enforces that downgrade anyway (red line) and lists it under Discrepancies.
+3. **Run** `roll attest {ID}` (add `--deploy-url <url>` when one exists). The report lands at `.roll/verification/{ID}/latest/report.html`.
+
 ### 11. Write Back Status (when tracking is needed)
 
 Only update when Hard Rule #6 conditions are met (user requested, affects roadmap-visible behavior, or needs follow-up tracking).
@@ -347,8 +364,11 @@ Both locations must be updated — neither can be skipped:
 
 **① Update .roll/backlog.md index row (Status column):**
 
+**Location rule (FIX-198)**: edit the MAIN project's backlog by ABSOLUTE path — `${ROLL_MAIN_PROJECT:-$PWD}/.roll/backlog.md`. In ordinary projects the cycle worktree has NO `.roll/` (gitignored, never checked out): a relative `.roll/backlog.md` edit writes into the void and the flip silently vanishes.
+
+
 ```markdown
-| [FIX-{ID}](.roll/features/<feature>.md#fix-{id}) | {Title} | ✅ Done |
+| [FIX-{ID}](.roll/features/<feature>.md#fix-{id}) | {Title} | ✅ Done · [evidence](.roll/verification/FIX-{ID}/latest/report.html) |
 ```
 
 Change the Status of the corresponding row 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.

package/bin/dream-test-quality-scan

@@ -1,110 +0,0 @@
-#!/usr/bin/env bash
-# dream-test-quality-scan — ad-hoc helper for roll-.dream Scan 7.
-#
-# Walks bats files and flags ❶-class anti-patterns (hardcoded business data
-# in assertion bodies). Emits structured REFACTOR-shaped lines so the
-# maintainer can sanity-check the rubric against the current suite without
-# waiting for the nightly dream cycle.
-#
-# Usage:
-#   dream-test-quality-scan [--category N] [--path PATH] [--max N]
-#   dream-test-quality-scan --help
-#
-# Only category 1 (❶ hardcoded business data) is implemented as a deterministic
-# heuristic; categories ❷..❻ stay with the dream skill (AI agent applies the
-# rubric). The helper exists so a smoke test and a maintainer dry-run can
-# confirm ❶ detection keeps working as the suite evolves.
-
-set -euo pipefail
-
-CATEGORY=1
-TARGET=""
-MAX=5
-
-usage() {
-  cat <<'EOF'
-dream-test-quality-scan — Scan 7 ❶ dry-run helper
-
-Usage:
-  dream-test-quality-scan [--category N] [--path PATH] [--max N]
-  dream-test-quality-scan --help
-
-Options:
-  --category N   Anti-pattern category (only 1 is implemented; default 1)
-  --path PATH    File or directory to scan (default: tests/)
-  --max N        Maximum entries to emit (default: 5; matches dream skill cap)
-  --help         Show this message
-
-Output:
-  One line per finding:
-    [test-quality:❶] <file>:<line> — <one-line description>
-  Exit code is 0 even when nothing is found (dry-run is informational).
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --category) CATEGORY="${2:-1}"; shift 2 ;;
-    --path)     TARGET="${2:-}"; shift 2 ;;
-    --max)      MAX="${2:-5}"; shift 2 ;;
-    --help|-h)  usage; exit 0 ;;
-    *)          echo "unknown flag: $1" >&2; usage >&2; exit 2 ;;
-  esac
-done
-
-if [[ "$CATEGORY" -ne 1 ]]; then
-  echo "category $CATEGORY not yet implemented — only ❶ is mechanical" >&2
-  exit 0
-fi
-
-# Default scan root.
-if [[ -z "$TARGET" ]]; then
-  repo_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
-  TARGET="${repo_root}/tests"
-fi
-
-if [[ ! -e "$TARGET" ]]; then
-  echo "path not found: $TARGET" >&2
-  exit 2
-fi
-
-scan_file() {
-  local file="$1"
-  # ❶ heuristic — assertion lines whose RHS contains a numeric literal:
-  #   - lines containing `[[` or `[ ` (bats assertion syntax)
-  #   - AND containing `==` or `=` (equality)
-  #   - AND containing a decimal/integer literal of length ≥ 1 inside quotes
-  # Emits one entry per file (not per line) to stay under the rate cap.
-  local first_hit
-  first_hit=$(grep -nE '\[\[.*"[^"]*[0-9]+(\.[0-9]+)?[^"]*"' "$file" 2>/dev/null \
-              | head -1 || true)
-  [[ -z "$first_hit" ]] && return 1
-
-  local lineno
-  lineno=$(echo "$first_hit" | cut -d: -f1)
-  local rel
-  rel=$(python3 -c "import os,sys; print(os.path.relpath(sys.argv[1]))" "$file" 2>/dev/null || echo "$file")
-  printf '[test-quality:❶] %s:%s — assertion body hardcodes a numeric literal that likely owns its value elsewhere\n' \
-    "$rel" "$lineno"
-  return 0
-}
-
-emitted=0
-if [[ -d "$TARGET" ]]; then
-  # Iterate over .bats files under TARGET; stop after MAX hits.
-  # Exclude vendored bats-core helpers — those are framework tests, not ours.
-  while IFS= read -r f; do
-    case "$f" in
-      */tests/helpers/bats-*/*) continue ;;
-    esac
-    if scan_file "$f"; then
-      emitted=$((emitted + 1))
-      [[ "$emitted" -ge "$MAX" ]] && break
-    fi
-  done < <(find "$TARGET" -type f -name '*.bats' | sort)
-else
-  scan_file "$TARGET" && emitted=1 || true
-fi
-
-# Always succeed — dry-run is informational, the dream cycle decides what to do.
-exit 0