@seanyao/roll 3.606.2 → 3.607.1

package/package.json

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

package/skills/roll-build/SKILL.md

@@ -116,7 +116,7 @@ If `roll-design` cannot produce ≥2 sub-stories (story is already irreducible),
 
 ### Step 1: Read the Story
 
-1. Open `.roll/backlog.md`, find the US row, follow the link to `.roll/features/<feature>.md`
+1. Open `.roll/backlog.md`, find the US row, follow the link to `.roll/features/<epic>/<story>/spec.md`
 2. Read the full AC / Files / Dependencies section
 3. If a plan doc (`<feature>-plan.md`) exists, read it for context
 
@@ -233,7 +233,7 @@ Wait for the user's response before editing files. If the user does not object w
 
 - Use `$roll-design` to split vague request into INVEST-compliant User Stories
 - Insert US into `.roll/backlog.md` under the relevant Epic > Feature group
-- If a new `.roll/features/<feature>.md` is needed, create it
+- If a new story folder is needed, create `.roll/features/<epic>/<story>/spec.md` (with `roll idea` or manually)
 
 After creation, switch to **Story mode** and execute the first US immediately.
 
@@ -359,7 +359,7 @@ When any signal appears, **do not stop — flag it**:
 | REFACTOR-001 | {one-line plain-language description} | 📋 Todo |
 ```
 
-描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `.roll/features/autonomous-evolution/refactor-log.md`。
+描述写法：参见 AGENTS.md "Backlog descriptions" 规则。说清楚"什么需要改"以及"不改会怎样"，技术细节写在 `.roll/features/<epic>/refactor-log.md`。
 
 **refactor-log.md entry format:**
 
@@ -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)
 
@@ -599,13 +647,13 @@ Both locations must be updated — neither can be skipped:
 
 
 ```markdown
-| [US-{ID}](.roll/features/<feature>.md#us-{id}) | {Title} | ✅ Done · [evidence](.roll/verification/US-{ID}/latest/report.html) |
+| [US-{ID}](.roll/features/<epic>/US-{ID}/spec.md) | {Title} | ✅ Done · [evidence](.roll/features/<epic>/US-{ID}/delivery/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.
 For Fly mode: first append an index row under the appropriate Epic > Feature group, then mark it done.
 
-**② Update `.roll/features/<feature>.md` US section:**
+**② Update `.roll/features/<epic>/<story>/spec.md`:**
 
 ```markdown
 ## US-{ID} {Story Title} ✅

package/skills/roll-design/SKILL.md

@@ -102,32 +102,40 @@ Bug Fix 信号:
 
 ## Workspace Configuration
 
-Document structure (two-layer separation):
+Document structure (story-first layout, US-META-005):
 
 ```
-.roll/backlog.md                          # US index page (status + one-liner + link)
+.roll/backlog.md                          # story index (status + one-liner)
 .roll/features/
-  <feature>.md                      # US details (AC / Files / Dependencies)
-  <feature>-plan.md                 # Design document (why / how)
-.roll/domain/                        # DDD domain model (greenfield / cross-feature)
-  context-map.md                    # Bounded Contexts + 关系图
-  ubiquitous-language.md            # 统一语言词汇表
-  <context>-model.md                # 每个 Context 的 Tactical Model
+  <epic>/                                 # epic folder
+    <feature>.md                          # feature design doc (optional, multi-story overview)
+    <feature>-plan.md                     # design plan (optional)
+    <story>/                              # individual story folder (one per card)
+      spec.md                             # story definition (AC, depends-on, etc.)
+      index.html                          # auto-generated story portal
+      delivery/                           # attest evidence (auto-generated on Done)
+.roll/domain/                             # DDD domain model
+  context-map.md
+  ubiquitous-language.md
 ```
 
 **Important rules:**
-1. Plan files go in `.roll/features/<feature>-plan.md` (**no longer using** `docs/plans/`)
-2. US details go in the corresponding `.roll/features/<feature>.md`
-3. **FIX / IDEA detail files use ID-prefixed filenames**: `.roll/features/<epic>/FIX-097.md`, not `.roll/features/<epic>/some-descriptive-slug.md`. Reason: a single FIX is one card, not a long-lived feature; the ID is the most stable handle, descriptive slugs date quickly and break links. US can keep feature-slug naming (US lives inside a multi-Story feature file). Quick lookup: `ls .roll/features/<epic>/FIX-*.md` finds all bugs in that area without grepping content.
-4. .roll/backlog.md only contains index rows (one row per US), **do not write** AC / Files / Notes
-5. Domain model files go in `.roll/domain/` — create on first greenfield design, update incrementally
-6. **Do not** write to `~/.kimi/`, `~/.kimi-code/`, or any global config directory
-
-**File path resolution order:**
-1. Determine Feature ownership (based on the requirement domain: compiler / ingest / qa / ...)
-2. Feature file: `.roll/features/<feature>.md` (create if it doesn't exist)
-3. Plan file: `.roll/features/<feature>-plan.md` (create if it doesn't exist)
-4. .roll/backlog.md index row goes under the corresponding Epic > Feature group
+1. **Every story card gets its own folder**: `features/<epic>/<story>/`
+2. **spec.md is the single definition file** — contains full AC, Files, Dependencies
+3. **FIX / IDEA / US all follow the same folder layout** — `features/<epic>/FIX-097/spec.md`
+4. **Feature design docs stay at epic root** — `<feature>.md` and `<feature>-plan.md` are optional, multi-story design overviews
+5. **index.html is auto-generated** by `roll idea` (skeleton) and updated by `roll attest` (delivery section)
+6. **delivery/ is auto-created** by `roll attest` on Done — do not create manually
+7. .roll/backlog.md only contains index rows (one row per story), **do not write** AC / Files there
+8. Domain model files go in `.roll/domain/`
+9. **Do not** write to `~/.kimi/`, `~/.kimi-code/`, or any global config directory
+
+**File path resolution:**
+1. Determine epic from story ID prefix (e.g., US-META-* → backlog-lifecycle, FIX-* → query index.json)
+2. Create story folder: `.roll/features/<epic>/<story>/`
+3. Write spec.md: `.roll/features/<epic>/<story>/spec.md` (full AC + details)
+4. Backlog row links to: `.roll/features/<epic>/<story>/spec.md`
+5. Design / plan docs (when needed): `.roll/features/<epic>/<feature>.md` + `<feature>-plan.md`
 
 ## Non-Interactive Mode
 
@@ -633,10 +641,10 @@ Do **not** infer "approach confirmed" from the user's reaction to the comparison
 FEATURE="compiler"
 
 # 2. Write Plan document (if there is a solution design)
-PLAN_FILE=".roll/features/${FEATURE}-plan.md"
+PLAN_FILE=".roll/features/${EPIC}/${FEATURE}-plan.md"
 
-# 3. Append US section in .roll/features/<feature>.md (with full AC)
-FEATURE_FILE=".roll/features/${FEATURE}.md"
+# 3. Write story spec: .roll/features/<epic>/<story>/spec.md (full AC)
+# Story specs: .roll/features/<epic>/<story>/spec.md
 
 # 4. Append index row under the corresponding Epic > Feature group in .roll/backlog.md
 # | [US-XXX](.roll/features/compiler.md#us-xxx) | One-line description | 📋 Todo |
@@ -655,7 +663,7 @@ DOMAIN_DIR=".roll/domain/"
 **.roll/backlog.md index row (only write this one line):**
 
 ```markdown
-| [US-{DOMAIN}-{N}](.roll/features/<feature>.md#us-{domain}-{n}) | {one-line description} | 📋 Todo |
+| [US-{DOMAIN}-{N}](.roll/features/<epic>/US-{DOMAIN}-{N}/spec.md) | {one-line description} | 📋 Todo |
 ```
 
 `{one-line description}` 写法：用户能读懂的一句话，说清楚"能做什么"或"解决了什么麻烦"。不写实现细节、文件路径、函数名。细节和 AC 写在 `.roll/features/` 里。写好了可以直接当 CHANGELOG 条目用。
@@ -770,11 +778,11 @@ Each story must be:
 ### Feature Name
 | Story | Description | Status |
 |-------|-------------|--------|
-| [US-XXX](.roll/features/<feature>.md#us-xxx) | One-line description | 📋 Todo |
-| [US-YYY](.roll/features/<feature>.md#us-yyy) | One-line description | ✅ Done |
+| [US-XXX](.roll/features/<epic>/<story>/spec.md#us-xxx) | One-line description | 📋 Todo |
+| [US-YYY](.roll/features/<epic>/<story>/spec.md#us-yyy) | One-line description | ✅ Done |
 ```
 
-**Note**: .roll/backlog.md only contains index rows; full AC / Files / Dependencies go in `.roll/features/<feature>.md`.
+**Note**: .roll/backlog.md only contains index rows; full AC / Files / Dependencies go in `.roll/features/<epic>/<story>/spec.md`.
 
 ---
 

package/skills/roll-fix/SKILL.md

@@ -20,7 +20,7 @@ Use when:
 - It does not need to be split into multiple Stories / Actions to deliver
 
 **Workflow:**
-1. Read .roll/backlog.md index → Find FIX/BUG row → Follow link to `.roll/features/<feature>.md`
+1. Read .roll/backlog.md index → Find FIX/BUG row → Follow link to `.roll/features/<epic>/<story>/spec.md`
 2. Single Action (no splitting)
 3. Execute via TCR workflow
 4. Write back: update .roll/backlog.md status column + update FIX section in Feature file
@@ -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)
 
@@ -368,12 +419,12 @@ Both locations must be updated — neither can be skipped:
 
 
 ```markdown
-| [FIX-{ID}](.roll/features/<feature>.md#fix-{id}) | {Title} | ✅ Done · [evidence](.roll/verification/FIX-{ID}/latest/report.html) |
+| [FIX-{ID}](.roll/features/<epic>/FIX-{ID}/spec.md) | {Title} | ✅ Done · [evidence](.roll/features/<epic>/FIX-{ID}/delivery/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.
 
-**② Update `.roll/features/<feature>.md` FIX section:**
+**② Update `.roll/features/<epic>/<story>/spec.md`:**
 
 ```markdown
 ## FIX-{ID} {description} ✅