@seanyao/roll 4.629.1 → 4.630.1

package/package.json

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

package/skills/roll-build/SKILL.md

@@ -12,6 +12,12 @@ This hub keeps the routing boundary, hard gates, and execution skeleton in the i
 
 Load when a user gives a US-XXX story or asks to ship a feature through Roll TCR delivery, from clarification through verification and backlog write-back.
 
+## Operating Modes
+
+Used in **guided** mode when the owner explicitly starts a Story, and in
+**autonomous** mode when the loop scheduler dispatches an eligible Story. The
+same TCR, evidence, Evaluator, and release gates apply in both modes.
+
 ## When Not to Use
 
 - Pure design or backlog splitting without code; load roll-design.

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

@@ -701,7 +701,7 @@ story (loop or manual Phase 10.6) and earn the report at delivery time.
    screenshot captures the card's **declared** deliverable, taken from the
    story's frontmatter key `deliverable_url` (alias `screenshot_url`). It may be
    a URL, a local file, or carry a `#fragment` to deep-link a specific tab/view
-   (e.g. `.roll/features/index.html#casting`). The loop captures it with
+   (e.g. `https://app.example.test/casting#board`). The loop captures it with
    **headless Playwright** — no GUI browser window pops up, and a missing
    Chromium self-heals via an auto-install on first use. The red line: **never**
    screenshot roll's own attest report / dossier page and pass it off as the

package/skills/roll-design/SKILL.md

@@ -12,6 +12,12 @@ This hub keeps the routing boundary, hard gates, and execution skeleton in the i
 
 Load when the user wants to discuss approaches, design a solution, model domains, split work into INVEST stories, or write backlog/spec artifacts without coding.
 
+## Operating Modes
+
+Used in **guided** mode when the owner explicitly designs or splits work, and in
+**autonomous** mode only as the Planner capability selected by a `planned`
+execution profile. It must never silently start Builder work.
+
 ## When Not to Use
 
 - Existing US implementation; load roll-build.
@@ -38,7 +44,7 @@ Load when the user wants to discuss approaches, design a solution, model domains
 - Peer review gates apply only when explicitly available/requested.
 - No story decomposition until a detailed design exists and the owner has signed off (proportional to risk). Decomposition slices an agreed design — it is NOT a substitute for designing. If you cannot show at least one complete worked sample of the intended output/behavior, the design is NOT done.
 - **Evaluation contract (US-SKILL-030 — planner-builder-evaluator artifact contract)**: every newly split story spec MUST include an `**Evaluation contract:**` block with `expected_evidence` (each item: `kind`, `target`, `proves`) and `scorer_focus`. This artifact is authored by the planner and consumed by builder (roll-build/roll-fix reads before coding) and evaluator (peer score prompt reads the contract; attest surfaces planned-vs-delivered mapping) — not a fixed three-agent collaboration model. Genuinely trivial/internal stories may carry a one-item minimal block, but never omit it. See `references/full-contract.md` for the full template and rules.
-- **Visual-evidence contract (FIX-311 — design-phase gate)**: every story spec is born honest. By default each story MUST carry one AC that captures its user-visible surface (web/CLI/TUI), and a web/visual card MUST declare the real product surface in its spec frontmatter — `deliverable_url:` (alias `screenshot_url:`) pointing at the actual deliverable page (e.g. `.roll/features/index.html#casting`), NEVER the card's own dossier/report page. A card with genuinely no visual surface writes `screenshot_exempt: <reason>` (a naked `true`/`yes` is NOT a valid exemption — it must carry a reason). This is enforced, not advisory: `validateStoryVisualEvidence(specText)` in `packages/cli/src/lib/design-visual-evidence.ts` returns `ok:false` for a non-exempt spec with no visual-evidence AC, or one that declares a visual surface but no `deliverable_url`. Keyword matching may only RECOGNISE an exemption / an existing visual-evidence AC — it may NEVER be used to decide a card needs a screenshot (it always does, by default). This is the same contract the runtime enforce gate (FIX-309) and archive gate (FIX-334) hold; the three must agree.
+- **Visual-evidence contract (FIX-311 — design-phase gate)**: every story spec is born honest. By default each story MUST carry one AC that captures its user-visible surface (web/CLI/TUI), and a web/visual card MUST declare the real product surface in its spec frontmatter — `deliverable_url:` (alias `screenshot_url:`) pointing at the actual deliverable page (e.g. `https://app.example.test/casting#board`), NEVER the card's own dossier/report/archive page. A card with genuinely no visual surface writes `screenshot_exempt: <reason>` (a naked `true`/`yes` is NOT a valid exemption — it must carry a reason). This is enforced, not advisory: `validateStoryVisualEvidence(specText)` in `packages/cli/src/lib/design-visual-evidence.ts` returns `ok:false` for a non-exempt spec with no visual-evidence AC, or one that declares a visual surface but no `deliverable_url`. Keyword matching may only RECOGNISE an exemption / an existing visual-evidence AC — it may NEVER be used to decide a card needs a screenshot (it always does, by default). This is the same contract the runtime enforce gate (FIX-309) and archive gate (FIX-334) hold; the three must agree.
 
 ## Gotchas
 

package/skills/roll-design/references/engineering-checklist.md

@@ -10,7 +10,7 @@ defect, not a delivery omission.
 
 **Must verify (default = REQUIRED; exemption is the only opt-out):**
 - [ ] Every story carries one AC that captures its user-visible surface (web/CLI/TUI screenshot / 截图).
-- [ ] A web/visual card declares the real product surface in frontmatter — `deliverable_url:` (alias `screenshot_url:`) pointing at the actual deliverable page (e.g. `.roll/features/index.html#casting`), NEVER the card's own dossier/report page.
+- [ ] A web/visual card declares the real product surface in frontmatter — `deliverable_url:` (alias `screenshot_url:`) pointing at the actual deliverable page (e.g. `https://app.example.test/casting#board`), NEVER the card's own dossier/report/archive page.
 - [ ] A card with genuinely no visual surface records `screenshot_exempt: <reason>` (a naked `true`/`yes` is invalid — the reason is mandatory).
 
 **Enforced, not advisory:** `validateStoryVisualEvidence(specText)` in

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

@@ -739,7 +739,7 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 - A web/visual card MUST declare the real product surface it delivers:
   ```yaml
   ---
-  deliverable_url: .roll/features/index.html#casting   # alias: screenshot_url. The actual deliverable page, NEVER the card's own dossier/report page.
+  deliverable_url: https://app.example.test/casting#board   # alias: screenshot_url. The actual deliverable page, NEVER the card's own dossier/report/archive page.
   ---
   ```
 - **Pin down the deliverable surface — locate it, don't guess** (`deliverable_url` MUST be the EXACT page + anchor the story lands on):

package/skills/roll-fix/SKILL.md

@@ -12,6 +12,13 @@ This hub keeps the routing boundary, hard gates, and execution skeleton in the i
 
 Load when the user provides a FIX-XXX or BUG-XXX item, or asks for a focused hotfix/bugfix through Roll lighter TCR repair workflow.
 
+## Operating Modes
+
+Used in **guided** mode when the owner explicitly starts a FIX/BUG repair, and
+in **autonomous** mode when the loop scheduler dispatches an eligible FIX/BUG
+item. The same regression, evidence, Evaluator, and release gates apply in both
+modes.
+
 ## When Not to Use
 
 - Broad feature delivery; load roll-build.

package/skills/roll-loop/SKILL.md

@@ -12,6 +12,14 @@ This hub keeps the routing boundary, hard gates, and execution skeleton in the i
 
 Load when configuring, explaining, or operating Roll autonomous backlog execution loop that scans Todo work and dispatches US/FIX/REFACTOR items.
 
+## Operating Modes
+
+This skill is primarily **autonomous**: it describes the scheduler that dispatches
+eligible backlog work. It also documents the explicit mode switches:
+`roll loop on` / `roll loop resume` enter autonomous operation; `roll loop off` /
+`roll loop pause` return control to **guided** operation. Autonomous mode never
+bypasses pause, budget, route, evidence, Evaluator, or release gates.
+
 ## When Not to Use
 
 - One-shot story execution by a human agent; load roll-build or roll-fix.