@seanyao/roll 3.606.2 → 3.606.3

package/package.json

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

package/skills/roll-build/SKILL.md

@@ -576,18 +576,66 @@ Follow the repo's deployment path (Vercel / Railway / etc.) and record the deplo
 
 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.
 
+0. **Before/after pairing (owner ruling 2026-06-06)**: when the story CHANGES
+   existing behavior, capture the prior state (`screenshots/before-*.png`)
+   before building and the new state (`screenshots/after-*.png`) at acceptance —
+   contrast is the clearest evidence. Brand-new capability with no prior state:
+   skip the pair; capture the new surface only.
+
 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/...`):
+   `.roll/features/<epic>/{ID}/screenshots/*.png` — the DEFAULT evidence class for
+   every surface, **CLI included** (US-ATTEST-010): text evidence is the agent's
+   own report (nothing stops a fabricated `echo "✓ passed" > evidence.txt`); a
+   screenshot is an OS-level capture of really-rendered pixels — an independent
+   channel with a categorically higher forgery cost. Combined with the
+   never-overwritten run dirs (D4) and the render-layer red line, it is the
+   strongest link in the evidence chain.
+   `.roll/features/<epic>/{ID}/evidence/*.txt` (resolve `<epic>` via `.roll/index.json`; `roll attest` writes the report there as `{ID}-report.html`) — supplementary (searchable,
+   copyable); keep raw command outputs here, but do not let a text file be the
+   ONLY evidence for an AC that has a visible surface.
+
+   **CLI capture recipe**: run the verifying command in a REAL terminal (the
+   tmux observation window `roll-loop-<slug>` is a natural target — display the
+   proof there), then `screencapture -x -R <window-rect>` (macOS) into
+   `screenshots/`. Capture ONLY the relevant work area — a focused window, not
+   the whole desktop. Unattended cycles: drive the capture from the dispatcher
+   (deterministic), never hand-craft an image; if the capture channel is
+   unavailable (no GUI session / no permission), fall back to text evidence and
+   mark the AC `partial` with a note — never fake a screenshot.
+2. **Write the intent map** `.roll/features/<epic>/{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" }] }]
+   "evidence": [
+     { "kind": "screenshot", "label": "terminal run (real pixels)", "href": "../screenshots/ac1-terminal.png" },
+     { "kind": "text", "label": "vitest (supplementary)", "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`.
+3. **Run** `roll attest {ID}` (add `--deploy-url <url>` when one exists). The report lands at `.roll/features/<epic>/{ID}/latest/{ID}-report.html` (archive-per-card layout, US-META-001). The report is now layered (US-ATTEST-013): card context + conclusion/business badges + key screenshots up front, technical ANSI/command output folded into collapsed `<details>`, and a closing block (quality gate + evidence index + self-score).
+4. **Design QA checklist (US-ATTEST-013) — READABILITY ONLY**. After the report
+   renders, open it and run the checklist below. This is a presentation review of
+   the rendered HTML, NOT an evidence review.
+   **HARD RULE: this checklist NEVER changes any AC's status, evidence, or
+   `pass|readonly|partial|fail|blocked|claimed|missing` verdict.** Those are
+   fixed at step 2 (the ac-map) and enforced by the render-layer red line. If a
+   readability item fails, fix the *presentation* (a missing context field, an
+   uncropped screenshot, a layout overflow) — never edit a verdict to make the
+   report look cleaner.
+   - [ ] **首屏 10s 可懂** — a product/business reviewer grasps what shipped and
+     whether it passed within ten seconds, without scrolling into the technical fold.
+   - [ ] **390 / 320px 无横滚** — no horizontal scroll at mobile widths; before/after
+     pairs stack rather than overflow.
+   - [ ] **打印可读** — print preview (or print-to-PDF) is legible; AC cards don't
+     split awkwardly across pages.
+   - [ ] **状态不只靠颜色** — every status reads from its icon + bilingual word, not
+     color alone (colorblind-safe).
+   - [ ] **截图裁切与清晰度** — screenshots are cropped to the relevant work area and
+     legible; no full-desktop captures, no blurry/half-rendered frames.
+   If you cannot open the report (headless cycle), note that the design QA was
+   deferred and say so in the cycle report — do NOT silently skip it, and do NOT
+   substitute it for an evidence judgement.
 
 ### Phase 11: Write Back Status (REQUIRED)
 

package/skills/roll-fix/SKILL.md

@@ -343,18 +343,69 @@ Verify the shipped fix on the deployed target:
 
 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.
 
+0. **Before/after pairing (owner ruling 2026-06-06)**: for a FIX, capture the
+   BROKEN state at reproduction time (screenshot when the surface is visible —
+   terminal run, panel, page) into `screenshots/before-*.png`; after the fix
+   passes, capture the SAME surface into `screenshots/after-*.png`. The pair is
+   the strongest possible fix evidence — reviewers see the delta, not a claim.
+   Behavior-changing stories: same pattern where a prior state exists.
+   Brand-new capability with nothing to contrast: skip — never stage a fake
+   "before".
+
 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/...`):
+   `.roll/features/<epic>/{ID}/screenshots/*.png` — the DEFAULT evidence class for
+   every surface, **CLI included** (US-ATTEST-010): text evidence is the agent's
+   own report (nothing stops a fabricated `echo "✓ passed" > evidence.txt`); a
+   screenshot is an OS-level capture of really-rendered pixels — an independent
+   channel with a categorically higher forgery cost. Combined with the
+   never-overwritten run dirs (D4) and the render-layer red line, it is the
+   strongest link in the evidence chain.
+   `.roll/features/<epic>/{ID}/evidence/*.txt` (resolve `<epic>` via `.roll/index.json`; `roll attest` writes the report there as `{ID}-report.html`) — supplementary (searchable,
+   copyable); keep raw command outputs here, but do not let a text file be the
+   ONLY evidence for an AC that has a visible surface.
+
+   **CLI capture recipe**: run the verifying command in a REAL terminal (the
+   tmux observation window `roll-loop-<slug>` is a natural target — display the
+   proof there), then `screencapture -x -R <window-rect>` (macOS) into
+   `screenshots/`. Capture ONLY the relevant work area — a focused window, not
+   the whole desktop. Unattended cycles: drive the capture from the dispatcher
+   (deterministic), never hand-craft an image; if the capture channel is
+   unavailable (no GUI session / no permission), fall back to text evidence and
+   mark the AC `partial` with a note — never fake a screenshot.
+2. **Write the intent map** `.roll/features/<epic>/{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" }] }]
+   "evidence": [
+     { "kind": "screenshot", "label": "terminal run (real pixels)", "href": "../screenshots/ac1-terminal.png" },
+     { "kind": "text", "label": "vitest (supplementary)", "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`.
+3. **Run** `roll attest {ID}` (add `--deploy-url <url>` when one exists). The report lands at `.roll/features/<epic>/{ID}/latest/{ID}-report.html` (archive-per-card layout, US-META-001). The report is now layered (US-ATTEST-013): card context + conclusion/business badges + key screenshots up front, technical ANSI/command output folded into collapsed `<details>`, and a closing block (quality gate + evidence index + self-score). A FIX usually carries a before/after pair (`screenshots/before-*.png` + `after-*.png`) — the坏态/好态 contrast is the clearest proof a bug is gone.
+4. **Design QA checklist (US-ATTEST-013) — READABILITY ONLY**. After the report
+   renders, open it and run the checklist below. This is a presentation review of
+   the rendered HTML, NOT an evidence review.
+   **HARD RULE: this checklist NEVER changes any AC's status, evidence, or
+   `pass|readonly|partial|fail|blocked|claimed|missing` verdict.** Those are
+   fixed at step 2 (the ac-map) and enforced by the render-layer red line. If a
+   readability item fails, fix the *presentation* (a missing context field, an
+   uncropped screenshot, a layout overflow) — never edit a verdict to make the
+   report look cleaner.
+   - [ ] **首屏 10s 可懂** — a reviewer grasps what was fixed and whether it passed
+     within ten seconds, without scrolling into the technical fold.
+   - [ ] **390 / 320px 无横滚** — no horizontal scroll at mobile widths; before/after
+     pairs stack rather than overflow.
+   - [ ] **打印可读** — print preview (or print-to-PDF) is legible; AC cards don't
+     split awkwardly across pages.
+   - [ ] **状态不只靠颜色** — every status reads from its icon + bilingual word, not
+     color alone (colorblind-safe).
+   - [ ] **截图裁切与清晰度** — screenshots are cropped to the relevant work area and
+     legible; no full-desktop captures, no blurry/half-rendered frames.
+   If you cannot open the report (headless cycle), note that the design QA was
+   deferred and say so in the cycle report — do NOT silently skip it, and do NOT
+   substitute it for an evidence judgement.
 
 ### 11. Write Back Status (when tracking is needed)