@seanyao/roll 3.628.1 → 4.629.1

package/package.json

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

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

@@ -45,3 +45,7 @@ Load when a build, fix, review, or story needs Roll QA coverage standards: test
 - 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.
+
+## Role in v4 execution profiles
+
+These QA standards are an **Evaluator capability** in the `verified`/`planned` execution profiles: the independent Evaluator applies them to judge story satisfaction and produces an `eval-report.md` (blocking findings, advisory findings, score, attest/evidence status, recommendation) — distinct from CI feedback and from the Builder's self-report. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)

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

@@ -146,3 +146,7 @@ In each micro-step of `$roll-build`:
 - **Check Phase**: Local quality control
 - **Micro-steps**: Small fast steps, each review < 100 lines
 - **TCR**: Can only commit after passing self-check, ensuring repo quality
+
+## Role in v4 execution profiles
+
+Self-review is a TCR-step quality gate **within the Builder role** — it is NOT story acceptance. In the `verified`/`planned` execution profiles the independent **Evaluator** (a fresh session, never the Builder's) judges whether the delivery satisfies the contract; blocking review, score, and attest stay three SEPARATE dimensions (never one pass/fail). This skill is one Evaluator capability among review/qa/scoring. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)

package/skills/roll-build/SKILL.md

@@ -26,7 +26,7 @@ Load when a user gives a US-XXX story or asks to ship a feature through Roll TCR
 
 1. Classify input as Story mode or Fly mode.
 2. Read backlog/spec and decide if the story fits one cycle.
-3. Split into small TCR actions and define verification.
+3. Split into small TCR actions; per Action route objective work to the 4-stage TCR loop and judgment-dependent work to a 3-stage criteria+Evaluator loop, then define verification.
 4. Run test-first implementation, self-review, evidence, and write-back.
 5. Commit on green, open PR, and leave remote evidence.
 
@@ -34,6 +34,7 @@ Load when a user gives a US-XXX story or asks to ship a feature through Roll TCR
 
 - TCR for every micro-step.
 - No WIP commits or bypassed verification.
+- In the test-gated loop the tests are the weakest link: an isolated Test Adequacy reviewer (Phase 6 Agent 4) audits the tests against the AC, seeing only AC + test files — never the implementation diff or builder reasoning. Self-review of one's own tests (Phase 2) is necessary but not isolation.
 - Self-review, attest, and E2E evidence remain required. The Review Score is produced by the runner's fresh-session peer Reviewer — the agent does NOT self-score.
 - Docs/code/product alignment is a DoD gate: user-visible behavior, command, output-copy, site, or delivery-view changes update the touched README/docs/guide/site/help in the same delivery.
 
@@ -47,3 +48,7 @@ Load when a user gives a US-XXX story or asks to ship a feature through Roll TCR
 - 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.
+
+## Role in v4 execution profiles
+
+**roll-build is the Builder capability in every execution profile** (`standard` / `verified` / `planned`). Under `planned` it receives the Planner's `planner-contract.md` via artifact refs (no shared raw session). Under `verified`/`planned` an independent **Evaluator** (a fresh session) judges the delivery and may open a BOUNDED repair round — you address the blocking findings and write a repair note mapping findings → changes. `standard` is Builder-only. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)

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

@@ -117,6 +117,7 @@ the command decides. The cap exists purely to stop infinite split chains.
 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
+4. **Read the Evaluation contract (US-SKILL-030)**: if the spec contains an `**Evaluation contract:**` block, read `expected_evidence` and `scorer_focus` before writing any code. This is the planner's artifact contract — use it to inform test design and evidence planning. Map each `expected_evidence` item to a planned Action or test; if an item is impossible given the actual scope, note the deviation in your report/ac-map. `builder_notes` carry planner hints — treat them as bounded guidance, not hidden requirements.
 
 ### Step A3: Split into Actions
 
@@ -180,6 +181,43 @@ When parallel conditions are not met, execute Actions sequentially.
 - What "online verification" means for this repo (URL, endpoint, UI flow, log signal)
 - Reference `$roll-.qa` for test pyramid (unit → E2E → visual → smoke)
 
+#### A4.1 Testability routing (objective 4-stage vs subjective 3-stage)
+
+Before defining the verification, classify **each Action** on one axis:
+
+> **Can this Action's acceptance be expressed as deterministic pass/fail tests?**
+
+```
+Action acceptance
+  ├── YES (deterministic) → objective 4-stage loop  ← DEFAULT
+  │      Planner (AC/contract) → Tester (Phase 2 + write RED)
+  │      → Builder (Phase 3 TCR) → Evaluator (Phase 6, incl. Agent 4 test audit)
+  │
+  └── NO (judgment-dependent) → subjective 3-stage loop
+         Planner emits EXPLICIT evaluation criteria up front
+         → Builder produces the output
+         → an ISOLATED Evaluator scores the output against those criteria
+```
+
+Most code Actions are objective — the test IS the contract; stay on the default
+path. Route to the 3-stage loop only for the genuinely judgment-dependent slices
+that still ride inside a delivery: output-copy wording, layout / visual polish,
+docs readability, recommendation quality. For those:
+
+- **Write the criteria before building** — the same discipline as a test, but in
+  prose: a short checklist of what "good" means for this Action (e.g. the Phase 11
+  design-QA checklist is exactly such a criteria set for a visual surface).
+- **Do not fake a test** to force the work onto the TCR path, and **do not let the
+  building agent grade its own output** — that is the self-score red line (FIX-343).
+- **An isolated Evaluator scores against the criteria** — a fresh session or
+  `$roll-peer` (which already enforces the Independent Judgment Rule: the evaluator
+  is not seeded with the builder's reasoning). Its verdict feeds the same
+  fix-and-recheck loop as a failing test.
+
+A single Story usually mixes both: the logic is objective (4-stage), while a copy
+or readability slice inside it is subjective (3-stage). Classify per Action, not
+per Story.
+
 Proceed to the **Shared TCR Workflow** (Phase 1 onward).
 
 ---
@@ -297,6 +335,12 @@ Reference `$roll-.qa` for coverage requirements and test pyramid strategy.
 
 **Why this phase**: TCR only guarantees code passes tests — verify tests are correct first.
 
+> This self-review is necessary but **not** sufficient: the same agent that
+> wrote the tests judging its own tests is not isolation. It catches obvious
+> gaps now; the *independent* adequacy audit (no implementation, no builder
+> reasoning) happens at **Phase 6 Agent 4 — Test Adequacy Review**. Treat this
+> step as "don't ship obviously-wrong tests," not as the final word on coverage.
+
 ### Phase 3: TCR Implementation Loop
 
 ```
@@ -477,27 +521,53 @@ across files, copy-paste patterns, cross-file N+1, etc.).
 git diff main...HEAD
 ```
 
-**Launch three review agents in parallel** (each receives the full diff):
+**Launch four review agents in parallel:**
 
 ```
-Agent 1: Reuse Review
+Agent 1: Reuse Review                 (receives: full diff)
   → Search for existing utilities / helpers the new code could use instead
   → Flag any new function that duplicates existing functionality
   → Flag inline logic replaceable by existing tools
 
-Agent 2: Quality Review
+Agent 2: Quality Review               (receives: full diff)
   → Redundant state, Parameter sprawl, Copy-paste near-duplicate,
      Leaky abstraction, Stringly-typed, JSX nesting,
      Nested conditionals ≥3 deep, Unnecessary comments
 
-Agent 3: Efficiency Review
+Agent 3: Efficiency Review            (receives: full diff)
   → Redundant computation / N+1, Missed concurrency,
      Hot-path bloat, Loop no-op updates, TOCTOU existence pre-check,
      Memory leaks, Overly broad operations
+
+Agent 4: Test Adequacy Review         (receives: AC/contract + test files ONLY)
+  → Audit the TESTS, not the implementation. This agent does NOT receive
+     the implementation diff or any builder reasoning — only (a) the Story's
+     AC / interface contract (the Planner artifact) and (b) the test files.
+  → AC ↔ assertion coverage: every AC has at least one test that would fail
+     if that AC regressed. Flag any AC with no corresponding assertion.
+  → Tautological / vacuous assertions: tests that only assert "did not throw",
+     re-assert the mock, or compare a value to itself — green but proves nothing.
+  → Tests loosened to pass: an assertion weakened (widened matcher, deleted
+     case, `.skip`, snapshot blindly updated) so a thin implementation goes green.
+  → Missing edge / failure cases the AC names (boundaries, invalid input,
+     concurrency, error paths) that have no test.
 ```
 
-Wait for all three agents to complete. Aggregate findings → fix each issue
-(false positives: note and skip, no debate) → summarize what was fixed.
+**Why Agent 4 is isolated (the test-gated-loop insight)**: in the TCR loop the
+implementation is *already* constrained by the tests — a thin or wrong
+implementation cannot stay green. The weakest link is therefore the **tests
+themselves**, and Phase 2's test-design review is a *self*-review by the same
+agent that wrote them (no isolation). Agent 4 closes that gap: a fresh,
+context-isolated reviewer that sees only the contract and the tests audits
+whether the tests actually pin the behavior the AC promises. Seeding it with the
+implementation diff or the builder's reasoning would collapse the independence
+(same red line as the FIX-343 Review Score and roll-peer's Independent Judgment
+Rule) — so it is deliberately withheld.
+
+Wait for all four agents to complete. Aggregate findings → fix each issue
+(false positives: note and skip, no debate) → summarize what was fixed. A
+genuine test-adequacy gap (uncovered AC, vacuous assertion) is fixed by a new
+TCR cycle that adds the missing test FIRST (RED), never by relaxing the audit.
 
 **Fallback**: If parallel agent invocation fails, run `$roll-.review staged` on
 the full diff as a single-pass fallback — do not skip review entirely.
@@ -622,8 +692,8 @@ story (loop or manual Phase 10.6) and earn the report at delivery time.
    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
+   the whole desktop. Unattended cycles: drive the capture from the runner's
+   capture lane (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.
 
@@ -650,6 +720,7 @@ story (loop or manual Phase 10.6) and earn the report at delivery time.
    ] }]
 ```
 
+   **Cross-reference with the Evaluation contract** (when present): each `expected_evidence` item in the contract maps to an AC via its `proves` field. When writing ac-map entries, ensure every `expected_evidence` item is addressed — the attest gate later surfaces a planned-vs-delivered delta from this mapping (US-SKILL-030).
    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/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 + Review Score).
 4. **Design QA checklist (US-ATTEST-013) — READABILITY ONLY**. After the report

package/skills/roll-design/SKILL.md

@@ -28,7 +28,7 @@ Load when the user wants to discuss approaches, design a solution, model domains
 1. Clarify only when intent or boundaries are unclear.
 2. Model domain depth proportional to risk and novelty.
 3. Detailed design before decomposition — for any non-trivial work, produce a concrete, implementable design artifact and get owner sign-off: (a) data/contract schema, (b) AT LEAST ONE complete worked sample of the intended output/behavior, (c) key interface signatures, (d) mapping/normalization rules, (e) edge cases & failure modes. Depth scales with risk/novelty; trivial work may be light.
-4. Split into INVEST stories — each a slice of the agreed detailed design.
+4. Split into INVEST stories — each a slice of the agreed detailed design. For every newly split story, write an `**Evaluation contract:**` block (expected_evidence + scorer_focus) — see the full contract's Story Format for the template. Genuinely trivial/internal stories may use a one-item minimal block, but never omit it.
 5. Write specs through roll story new and update backlog.
 
 ## Hard Gates
@@ -37,6 +37,7 @@ Load when the user wants to discuss approaches, design a solution, model domains
 - Backlog rows and spec files must stay consistent.
 - 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.
 
 ## Gotchas
@@ -50,3 +51,7 @@ Load when the user wants to discuss approaches, design a solution, model domains
 - 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.
+
+## Role in v4 execution profiles
+
+In the `planned` execution profile, **roll-design is the Planner capability**: in a FRESH session before the Builder it writes a `planner-contract.md` (scope boundary, acceptance/evaluation contract, expected evidence, risks, out-of-scope items, resize/split guidance) that the Builder consumes via artifact refs. roll-design stays a skill — the TS engine owns orchestration and validates the contract fail-closed before the Builder starts. For pure design/backlog planning the user loads roll-design directly; it does not auto-trigger. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)

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

@@ -721,6 +721,20 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 - [ ] {measurable criteria 3}
 - [ ] {visual-evidence AC — REQUIRED by default: a captured screenshot of this story's user-visible surface (web/CLI/TUI). For a web/visual card this is "screenshot of <the deliverable page> is captured", paired with the `deliverable_url:` frontmatter below. Omit this AC ONLY when the card is `screenshot_exempt:` (see frontmatter).}
 
+**Evaluation contract:**
+- expected_evidence:
+  - kind: test | command | screenshot | document | diff | ci | manual
+    target: {file/command/surface/report expected to prove an AC}
+    proves: {AC id or short AC phrase this evidence proves}
+- scorer_focus:
+  - {what the peer Review Score should judge beyond generic code quality}
+- builder_notes:
+  - {bounded implementation/evidence hints; no hidden requirements}
+
+> **强制规则 — Evaluation contract 必须填**：每张新 story 必须带 `**Evaluation contract:**` 块（expected_evidence + scorer_focus）。这是 planner 写给 builder 和 evaluator 的验收契约——builder 编码前读 contract、交付后把 ac-map 项映射回 contract 的 expected_evidence；evaluator（peer score / attest gate）读 contract 对账。不是固定三 agent 协同模型，是 artifact-based 契约。真正 trivial/internal 故事可放一项 minimal block，但不许省略。
+>
+> **MUST fill** the `**Evaluation contract:**` block on every newly split story. This is an artifact contract authored by roll-design, consumed by builder (read before coding, map delivered evidence back) and evaluator (peer score prompt includes it, attest surfaces planned-vs-delivered). Genuinely trivial/internal stories may use a one-item minimal block, never omit it.
+
 **Spec frontmatter (visual-evidence contract — FIX-311):**
 - A web/visual card MUST declare the real product surface it delivers:
   ```yaml
@@ -757,6 +771,25 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 >
 > **MUST fill** the `**Agent profile:**` block on every newly split US. `est_min` is the **sole loop-routing input** — `lib/loop_pick_agent.py` maps it onto a four-slot complexity tier (easy/default/hard/fallback) on the est_min axis alone (missing/illegal → default). Fill `risk_zone` too, but note it does NOT feed routing; it only informs the roll-build / roll-fix pre-flight self-eval (US-AGENT-007).
 
+> **强制规则 — Evaluation contract 必须填（US-SKILL-030）**：每张新 story spec 都必须包含 `**Evaluation contract:**` 块，明确列出 `expected_evidence`（每项 kind/target/proves 三字段）和 `scorer_focus`（peer scorer 评分口径）。纯内部/无可见面的 trivial story 可使用 one-item 最小块，但不可省略。该块由 planner（`roll-design`）撰写，供 builder 和 evaluator 作为共享证据契约消费，不触发三 agent 协同会话。
+
+> **Evaluation contract is required (US-SKILL-030)**: every newly split story spec MUST carry an `**Evaluation contract:**` block with `expected_evidence` (each item: `kind`, `target`, `proves`) and `scorer_focus` (scorer rubric). Genuinely trivial/internal stories may use a one-item minimal block but must not omit the section entirely. This block is authored by the planner (`roll-design`) and consumed as a shared artifact contract by builder (`roll-build`/`roll-fix`) and evaluator (peer scorer, attest gate) — no three-agent chat pipeline is introduced.
+>
+> **Block template:**
+> ```markdown
+> **Evaluation contract:**
+> - expected_evidence:
+>   - kind: test | command | screenshot | document | diff | ci | manual
+>     target: <file/command/surface/report that proves an AC>
+>     proves: <AC id or short AC phrase>
+> - scorer_focus:
+>   - <what the peer Review Score should judge beyond generic code quality>
+> - builder_notes:
+>   - <bounded implementation/evidence hints; no hidden requirements>
+> ```
+>
+> **Rules**: (1) `expected_evidence` items are **binding for evidence expectations** — if an item becomes impossible, the builder updates the spec or explains the deviation in the report/ac-map. (2) `scorer_focus` items extend, not replace, the generic scoring rubric. (3) This block complements the visual-evidence contract; `deliverable_url`/`screenshot_exempt` rules are unchanged. (4) Legacy specs without the block degrade gracefully — builder and scorer fall back to the generic rubric with no behavior change.
+
 ### Closing Doc-Refresh Story Template — Phase N.M 收尾文档
 
 When any preceding US in the batch changes user-visible behavior, append this template story at the end of the batch. Wire it as `depends-on:` against every preceding user-facing US so it runs last.
@@ -837,6 +870,29 @@ The design-side peer Review Score path is tracked by **FIX-344** (the runner's
 score stage does not yet cover `roll-design`). Until FIX-344 lands, this skill
 emits no quality score; the agent just delivers the split + specs and stops.
 
+### The 3-stage shape (subjective deliverable)
+
+A design has **no executable pass/fail test** — correctness is judgment. So it is
+the canonical **3-stage loop**, and naming the stages keeps the roles honest:
+
+- **Planner / Builder = this design session.** Besides the split + specs, it must
+  emit **explicit evaluation criteria for the design itself** — the prose
+  equivalent of a test contract: what would make this design wrong or incomplete
+  (e.g. "every Bounded Context boundary is justified", "the worked sample covers
+  the hardest edge case", "no story depends on a parked parent", "each
+  user-facing story carries a visual-evidence AC"). Write these down so the
+  Evaluator has something concrete to check against rather than a vibe.
+- **Evaluator = an ISOLATED reviewer.** It receives the design artifact + the
+  criteria, and **must not be seeded with the designer's reasoning** (roll-peer's
+  Independent Judgment Rule already enforces exactly this — see the two
+  `[peer]` checkpoints in the Workflow: Direction Review and Plan Review). A
+  fresh same-vendor session is the minimum; a different agent+model is encouraged.
+
+Until the runner's FIX-344 stage lands, the isolated Evaluator is the
+`$roll-peer` Plan Review checkpoint, not an automated score — but the criteria
+above are what it should grade against either way. Emitting the criteria now is
+cheap and makes the future automated Evaluator a drop-in.
+
 ---
 
 ## Integration

package/skills/roll-fix/SKILL.md

@@ -47,3 +47,7 @@ Load when the user provides a FIX-XXX or BUG-XXX item, or asks for a focused hot
 - 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.
+
+## Role in v4 execution profiles
+
+**roll-fix is the Builder capability for hot-fix scope** (a single issue), normally under the `standard` execution profile — the same TCR/test/attest flow as roll-build, with no Planner or Evaluator. A fix that turns out user-visible or evidence-risky is selected into `verified`; one that turns out cross-module or ambiguous into `planned`. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)

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

@@ -20,9 +20,10 @@ Use when:
 
 **Workflow:**
 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
+2. **Read the Evaluation contract (US-SKILL-030)** if the spec contains an `**Evaluation contract:**` block. Read `expected_evidence` and `scorer_focus` before writing code; use them to guide test design and evidence collection. Map each evidence item to a planned change and map delivered evidence back to the contract in the ac-map; note any deviation if an item turns out to be N/A for a fix.
+3. Single Action (no splitting)
+4. Execute via TCR workflow
+5. Write back: update .roll/backlog.md status column + update FIX section in Feature file
 
 Do not use for:
 
@@ -389,8 +390,8 @@ Runs ONLY on a ✅ Gate PASS (a FAIL retry must not mint a misleading report). N
    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
+   the whole desktop. Unattended cycles: drive the capture from the runner's
+   capture lane (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/...`):

package/skills/roll-peer/SKILL.md

@@ -45,3 +45,7 @@ Load when the user explicitly asks for peer review, cross-agent negotiation, /pe
 - 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.
+
+## Role in v4 execution profiles
+
+Cross-agent peer review is an **Evaluator capability**: an independent fresh-session reviewer (never the Builder's session) scores the delivery. The Evaluator's judgment is binding for story satisfaction; peer negotiation is the mechanism. In `verified`/`planned` profiles this feeds the `eval-report.md`. (Roles: Supervisor Agent / Planner / Builder / Evaluator; never Prime/Watchman/Dispatcher/Governor.)

package/skills/roll-propose/SKILL.md

@@ -125,6 +125,12 @@ To reject:  annotate with "Rejected: {reason}" to suppress future re-proposals.
 - Never write directly to .roll/backlog.md — .roll/proposals.md is the staging area.
 - If a similar proposal already exists in .roll/proposals.md (pending or rejected), note similarity and skip or merge rather than creating a duplicate.
 - Aim for 2 proposals by default; generate 1 if context is thin, 3 if focus hint suggests a rich area.
+- **3-stage discipline**: a proposal is a subjective deliverable, so the drafting
+  session must NOT also approve it. The owner moving an entry into .roll/backlog.md
+  IS the isolated Evaluator (the human is the fresh, unbiased session the 3-stage
+  loop requires). The proposal's **Acceptance Criteria (draft)** are the explicit
+  criteria that approval is graded against — keep them concrete and checkable so
+  the decision is against stated criteria, not a vibe; never self-promote a draft.
 
 ## .roll/proposals.md Format