@seanyao/roll 3.615.1 → 3.617.1

package/package.json

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

package/skills/docs/skill-authoring.md

@@ -44,8 +44,11 @@ Every hub must include `## Gotchas` or `## Known Failure Modes`.
 - Treat the section as append-mostly unless an entry is proven obsolete.
 - Never instruct agents to `source "$(command -v roll)"`: the TS-native `roll`
   is a bundled CLI, not a bash library, and sourcing it executes JS as shell
-  (FIX-274). Skill steps call `roll <command>` directly — e.g. self-score notes
-  go through `roll self-score <skill> <story> <score> <verdict> "<rationale>"`.
+  (FIX-274). Skill steps call `roll <command>` directly.
+- Skills do NOT self-score (FIX-343). The working agent never scores its own
+  story; the Review Score is a runner-side peer-review outcome, produced by a
+  Reviewer in a FRESH, separate session (never a sub-agent of the builder's
+  session). Do not author any `self-score` step into a skill.
 
 ## Maintenance Workflow
 

package/skills/roll-build/SKILL.md

@@ -34,7 +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.
-- Self-review, attest, E2E evidence, and self-score remain required.
+- 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.
 
 ## Gotchas

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

@@ -314,14 +314,30 @@ $(msg build.micro_step {N} "{description of smallest testable change}")
       └── Write just enough to make test pass
 
    Step 3: TCR Decision
-      └── Run test
+      └── roll test  (per-commit gate — AFFECTED scope only)
           ├── ✅ GREEN → git commit -m "tcr: {micro-step description}"
           └── ❌ RED   → git checkout -- .  → Retry with new approach
 
    Step 4: Refactor (optional, while green)
-      └── Run test → ✅ GREEN → Amend or new TCR cycle
+      └── roll test → ✅ GREEN → Amend or new TCR cycle
 ```
 
+**The commit gate runs AFFECTED tests, not the full suite (FIX-325):**
+
+- `roll test` (the per-commit gate) runs `vitest --changed` — only the
+  dependency closure of the working-tree change — and **excludes** the
+  env-divergent heavy suites (`*.integration.test.ts`, `*.e2e.test.ts`,
+  `npm-pack.test.ts`) that are red locally / in a cycle worktree but green in
+  CI. The FULL suite (`npm test`, no `--affected`) is the CI / pre-push gate
+  (Phase 5), never the per-commit gate.
+- On green, `roll test` writes the proof record `.roll/last-test-pass`
+  (`{ts, tree, mode, scope}`). The `pre-commit` hook refuses the commit unless
+  that proof is **fresh (≤ 60s)** AND its `tree` matches the current
+  `git write-tree` — i.e. the exact code being committed was just tested. So:
+  stage → `roll test` → commit, in that order; editing after the test
+  invalidates the proof (commit blocked: "code changed since last test run").
+  Doc-only changes are exempt.
+
 **Micro-step guidelines:**
 
 | Change Type | Typical Micro-Steps |
@@ -411,7 +427,10 @@ E2E DEPOSIT
 
 ### Phase 5: Pre-Push CI Gate
 
-After all micro-steps, run full CI locally before pushing:
+After all micro-steps, run the **FULL** suite locally before pushing — this is
+where the heavy env-divergent suites (integration / e2e / npm-pack) excluded
+from the per-commit affected gate (Phase 3) finally run. This is the same scope
+CI runs (`npm test` with no `--affected`), so a green here predicts a green CI.
 
 ```bash
 npm run ci:local 2>/dev/null || (npm run lint && npm run build && npm test -- --run)
@@ -578,6 +597,15 @@ 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 12.
 
+**Attest is EARNED during delivery — never backfilled (FIX-329).** Acceptance
+evidence is produced inside the delivery: under `roll-loop` the HARD
+`attest:gate` renders the report in-cycle; on the manual path you run
+`roll attest` here, in Phase 10.6 of this delivery. There is no after-the-fact
+reconstruction — `roll attest backfill` was a loophole and has been **removed**
+(it now hard-errors). A Done card with no in-delivery evidence cannot acquire a
+report; the only way past the release consistency gate is to **re-deliver** the
+story (loop or manual Phase 10.6) and earn the report at delivery time.
+
 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 —
@@ -604,6 +632,20 @@ Runs ONLY on a ✅ Gate PASS (a FAIL retry must not mint a misleading report). N
    (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.
+
+   **Web capture — shoot the DELIVERABLE, not the dossier (FIX-321/314)**: a web
+   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
+   **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
+   deliverable — that is a hollow shot. If the card declares **no**
+   `deliverable_url`, the capture **honestly skips** (recorded as a real skip,
+   not a fabricated image) — that is the correct behavior, not a failure. Declare
+   `deliverable_url` in the spec frontmatter when the story ships a visible web
+   surface so the real view gets captured.
 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
@@ -615,7 +657,7 @@ Runs ONLY on a ✅ Gate PASS (a FAIL retry must not mint a misleading report). N
 ```
 
    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 + self-score).
+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
    renders, open it and run the checklist below. This is a presentation review of
    the rendered HTML, NOT an evidence review.
@@ -641,6 +683,20 @@ Runs ONLY on a ✅ Gate PASS (a FAIL retry must not mint a misleading report). N
 
 ### Phase 12: Write Back Status (REQUIRED)
 
+**Done ≡ merged (FIX-322/323).** A card is `✅ Done` only once its delivery is
+**merged to `main`** — not when the branch is pushed and not while the PR is
+merely open. `published_pending_merge` (pushed / PR open, awaiting merge) is
+**not** delivered. Consequences you can rely on:
+
+- The picker **skips** any card that already has a merged delivery, so a card
+  reset to 📋 Todo after merge is not re-picked and re-built.
+- Preflight reconciles truth from the PR: a 🔨 In Progress card whose PR has
+  **MERGED** is flipped to ✅ Done automatically (an OPEN PR is left alone).
+
+So on the manual path, flip the row to Done **after** the PR merges; under
+`roll-loop` the runner waits for green CI, auto-merges, and the flip follows the
+merge — do not pre-flip on a still-open PR.
+
 Both locations must be updated — neither can be skipped:
 
 **① Update .roll/backlog.md index row (Status column):**
@@ -738,9 +794,14 @@ Before creating any file or directory:
    worktree + branch and opens the PR; this rule is the manual-path
    equivalent and must hold either way.)
 
-1. **No local-only "done"**
+1. **No local-only "done" — Done ≡ merged (FIX-322/323)**
    Work is not complete until it reaches:
-   commit → push → CI signal → deploy → online verification → backlog update
+   commit → push → CI signal → **PR merged to main** → deploy → online
+   verification → backlog update.
+   A pushed branch or an open PR is `published_pending_merge`, NOT delivered;
+   the row flips to `✅ Done` only after the merge. Truth reconciles from the
+   PR: the picker skips already-merged cards and preflight flips a MERGED PR's
+   card to Done.
 
 2. **TCR for every micro-step**
    - Each behavior change: Test → Green=Commit / Red=Revert
@@ -792,33 +853,24 @@ Before creating any file or directory:
 - [ ] **.roll/backlog.md index status updated** (📋 → ✅, REQUIRED)
 - [ ] **`.roll/features/<feature>.md` US section updated** (Completed date + [x] ACs, REQUIRED)
 - [ ] **CHANGELOG.md staged and bundled** into completion commit via `$roll-.changelog` in Phase 12 (REQUIRED)
-- [ ] **Self-score note written (US-SKILL-010 / 012)** — see "Self-score" subsection below
 - [ ] Summary reported to user
 
-### Self-score (US-SKILL-012)
-
-Before reporting completion to the user, ensure one score note lands.
-**Pair-first (US-PAIR-009/010): when `.roll/pairing.yaml` enables the `score`
-stage, the paired heterogeneous agent produces the score — self-score is the
-fallback, not the default.** Run from the main project root (the directory
-holding `.roll/`); the note lands under `.roll/features/<epic>/<US-id>/notes/<date>-roll-build-<US-id>-<epoch>.md` (the card folder is the note home, US-META-008; epic resolution and the `.roll/notes/` fallback are built in)
-with YAML frontmatter so trend analysis (US-SKILL-014) can aggregate later:
-
-```bash
-# 1. pair-first: ask the paired heterogeneous agent to score the cycle
-roll pair score US-XXX-NNN --summary "<one-paragraph delivery summary>"
-# 2. ONLY when the command prints a fallback hint (pairing off / no candidate /
-#    timeout), write the self-score with the printed reason:
-roll self-score roll-build US-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>" --fallback-reason "<reason>"
-```
+### Review Score (FIX-343)
 
-Both commands are idempotent — retrying after a transient failure is safe.
+The story's Review Score is **not** produced by this skill. The building agent
+**does NOT self-score**. The quality score is produced SOLELY by the runner's
+peer score stage — a Reviewer running in a FRESH, separate session (never a
+sub-agent of the builder's session). The agent's job is to deliver clean
+evidence (report + ac-map + attest); the runner then casts a fresh-session
+Reviewer that mints the Review Score (1..10 + verdict + rationale), recorded
+with `scoredBy` and the fresh-session id so independence is verifiable.
 
-> FIX-274: the TS-native `roll` is a bundled CLI and MUST NOT be sourced as a
-> bash library — the old `source`-based `_skill_write_self_score`
-> path is dead. Retrying after a transient failure is safe (idempotent).
+Independence is about session/context, not vendor: a fresh same-vendor session
+is the minimum acceptable; a different agent+model+session (non-sub-agent) is
+encouraged (absolute heterogeneity). A score sharing the builder's session
+(including any sub-agent of it) is rejected as a self-score.
 
-Score guidance (integer 1..10):
+Score guidance the Reviewer applies (integer 1..10):
 - **9..10** — story shipped cleanly: AC fully met, TCR rhythm tight, no
   re-tries from `verdict: too_big`, peer review concerns addressed inline.
 - **6..8** — shipped with caveats: re-tries on red, edge case left to a

package/skills/roll-design/SKILL.md

@@ -30,7 +30,6 @@ Load when the user wants to discuss approaches, design a solution, model domains
 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.
 5. Write specs through roll story new and update backlog.
-6. Self-score the design quality.
 
 ## Hard Gates
 
@@ -38,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.
+- **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
 

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

@@ -2,6 +2,32 @@
 
 > **These are not best practices — they are baseline requirements.** Violations are bugs.
 
+## 0. Visual Evidence Contract (FIX-311) 📸
+
+**Definition:** A spec must be born honest — its design already names HOW the
+delivery will prove its user-visible surface. A missing screenshot is a DESIGN
+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 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
+`packages/cli/src/lib/design-visual-evidence.ts` returns `ok:false` for a
+non-exempt spec missing a 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 — never decide a card needs a
+screenshot (it always does, by default). Same contract the runtime enforce gate
+(FIX-309) and archive gate (FIX-334) hold; the three must agree.
+
+**Counter-example (FIX-284):** ① a card declared a deliverable url yet wired no
+capture AC → honest-skip / empty shell forever; ② a clear UI redesign lacking
+the literal keyword slipped the iron rule (keyword-as-enabler leak). Both are
+caught here at the spec source.
+
+---
+
 ## 1. Idempotency 🔁
 
 **Definition:** Performing the same operation N times produces the same result as performing it once.

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

@@ -719,6 +719,25 @@ Note: `{DOMAIN}` maps to the Bounded Context name identified in DDD analysis.
 - [ ] {measurable criteria 1}
 - [ ] {measurable criteria 2}
 - [ ] {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).}
+
+**Spec frontmatter (visual-evidence contract — FIX-311):**
+- 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.
+  ---
+  ```
+- **Pin down the deliverable surface — locate it, don't guess** (`deliverable_url` MUST be the EXACT page + anchor the story lands on):
+  - *Existing surface* → cite the real tab/anchor and VERIFY it exists (grep the generated page for the `#anchor`); never a parent or plausible-but-wrong page.
+  - *New feature* → DECIDE and NAME where it lands (which page / tab / route it is added to); that landing point IS the `deliverable_url` (it may not exist until this story builds it — that is expected; FIX-309 will require a real capture of it at attest, so a wrong/empty target fails loud).
+  - Never the card's dossier; never a generic page when the story changes a specific sub-surface.
+- A card with genuinely NO user-visible surface (pure data-migration, infra, …) instead records:
+  ```yaml
+  ---
+  screenshot_exempt: pure data-migration — no user-visible surface   # a naked `true`/`yes` is NOT valid; the reason is mandatory.
+  ---
+  ```
 
 **Files:**
 - `{file1}`
@@ -807,48 +826,16 @@ Each story must be:
 
 ---
 
-## Self-score (US-SKILL-010 / 013)
+## Review Score (FIX-343)
 
-After Step 5 (Write to BACKLOG) completes — i.e. once the new US rows are
-landed and the user has either confirmed or chosen `No` (story still
-queued) — write a single self-score note covering the design session:
+The design session is **not** self-scored. The designing agent **does NOT
+self-score**. A design Review Score — when one is produced — comes SOLELY from
+a Reviewer running in a FRESH, separate session (never a sub-agent of the
+designer's session), the same independence rule as build/fix.
 
-```bash
-# 1. pair-first (US-PAIR-009/010): when .roll/pairing.yaml enables the `score`
-#    stage, the paired heterogeneous agent scores the design session
-roll pair score US-XXX-NNN --skill roll-design --summary "<one-paragraph design-session summary>"
-# 2. ONLY when the command prints a fallback hint (pairing off / no candidate /
-#    timeout), write the self-score with the printed reason:
-roll self-score roll-design US-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>" --fallback-reason "<reason>"
-```
-
-> FIX-274: the TS-native `roll` is a bundled CLI and MUST NOT be sourced as a
-> bash library — the old `source`-based `_skill_write_self_score`
-> path is dead. Retrying after a transient failure is safe (idempotent).
-
-Use the **first** US-id of the batch as the story handle (or the
-representative story when splitting). Run from the main project root; when the
-story already has a card folder the note lands there, otherwise it falls back
-to `.roll/notes/<date>-roll-design-<id>-<epoch>.md` so US-SKILL-014 can
-read trend data.
-
-Score guidance for design quality (integer 1..10):
-- **9..10** — clean split: every US is INVEST-compliant, profile
-  (est_min / risk_zone / chain_depth) filled, doc-refresh closer wired
-  when user-visible behaviour changed, peer-review unnecessary or
-  reached AGREE quickly.
-- **6..8** — split shipped but with caveats: one US borderline on
-  INVEST (e.g. shared file conflict), or Discuss had ESCALATE before
-  settling, or profile was partial.
-- **1..5** — split shipped but rough: missing doc-refresh closer,
-  profile fields skipped, USer story too coarse for AI cycle; flag a
-  follow-up `roll-design` pass.
-
-Verdict values:
-- `good` — design + split are clean.
-- `ok` — design is acceptable with one or two trade-offs noted.
-- `regression` — the split visibly broke something earlier (rare; e.g.
-  invalidated a previously-stable depends-on chain).
+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.
 
 ---
 

package/skills/roll-fix/SKILL.md

@@ -34,7 +34,7 @@ Load when the user provides a FIX-XXX or BUG-XXX item, or asks for a focused hot
 
 - Every fix gets a regression signal or documented exception.
 - Blocking review findings are fixed in another TCR cycle.
-- Self-score note is required before exit.
+- 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.
 
 ## Gotchas

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

@@ -397,7 +397,7 @@ Runs ONLY on a ✅ Gate PASS (a FAIL retry must not mint a misleading report). N
 ```
 
    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 + 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.
+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). 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.
@@ -507,34 +507,22 @@ A minor change is only "done" when all are true:
 - [ ] Deployment completed
 - [ ] Online verification performed
 - [ ] **Verification Gate passed** (fresh evidence for tests, build, fix confirmation, no regression)
-- [ ] **Self-score note written (US-SKILL-010 / 011)** — before exit, the agent
-      writes a structured score note via `roll self-score` so trend
-      analysis (US-SKILL-014) and skill-self-scoring docs (US-SKILL-015) have
-      data to read.
-
-### Self-score (US-SKILL-011)
-
-Before exiting the cycle, ensure one score note lands. **Pair-first
-(US-PAIR-009/010): when `.roll/pairing.yaml` enables the `score` stage, the
-paired heterogeneous agent produces the score — self-score is the fallback,
-not the default.** Run from the main project root (the directory holding
-`.roll/`); the note lands under `.roll/features/<epic>/<FIX-id>/notes/<date>-roll-fix-<FIX-id>-<epoch>.md` (the card folder is the note home, US-META-008; epic resolution and the `.roll/notes/` fallback are built in):
-
-```bash
-# 1. pair-first: ask the paired heterogeneous agent to score the cycle
-roll pair score FIX-XXX-NNN --summary "<one-paragraph delivery summary>"
-# 2. ONLY when the command prints a fallback hint (pairing off / no candidate /
-#    timeout), write the self-score with the printed reason:
-roll self-score roll-fix FIX-XXX-NNN <score 1..10> <good|ok|regression> "<rationale>" --fallback-reason "<reason>"
-```
-
-Both commands are idempotent — retrying after a transient failure is safe.
-
-> FIX-274: the TS-native `roll` is a bundled CLI and MUST NOT be sourced as a
-> bash library — the old `source`-based `_skill_write_self_score`
-> path is dead. Retrying after a transient failure is safe (idempotent).
-
-Score guidance (integer 1..10):
+### Review Score (FIX-343)
+
+The Review Score is **not** produced by this skill. The fixing agent **does NOT
+self-score**. The quality score is produced SOLELY by the runner's peer score
+stage — a Reviewer running in a FRESH, separate session (never a sub-agent of
+the builder's session). The agent's job is to deliver clean evidence (report +
+ac-map + attest); the runner then casts a fresh-session Reviewer that mints the
+Review Score (1..10 + verdict + rationale), recorded with `scoredBy` and the
+fresh-session id so independence is verifiable.
+
+Independence is about session/context, not vendor: a fresh same-vendor session
+is the minimum acceptable; a different agent+model+session (non-sub-agent) is
+encouraged (absolute heterogeneity). A score sharing the builder's session
+(including any sub-agent of it) is rejected as a self-score.
+
+Score guidance the Reviewer applies (integer 1..10):
 - **9..10** — clean root-cause fix; regression test added; TCR cycle smooth.
 - **6..8** — fix shipped but with caveats (e.g. workaround, partial coverage,
   or repeated TCR red iterations); rationale explains the trade-off.