baldart 3.17.1 → 3.18.1

package/CHANGELOG.md

@@ -5,6 +5,106 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.18.1] - 2026-05-25
+
+Chiusura del debito tecnico introdotto da v3.18.0. Il release v3.18.0 ha annunciato che `/design-review` supporta un programmatic JSON output mode invocabile da `/e2e-review` per gating uniforme — ma l'implementazione era una sola nota nel frontmatter ("se invocato con `mode: programmatic` ritorna JSON") senza body command che la concretizzasse, senza schema vincolato, senza mode-detection deterministica, senza taxonomy mapping tra le severity Markdown (Blockers/High/Medium/Nitpicks) e le severity programmatic (critical/major/minor) del `visual-fidelity-verifier`. Il risultato: una feature half-implemented, parsable only in teoria. Questo PATCH la rende reale.
+
+L'adversarial review del piano v3.19.0 (multi-viewport + interactive states + Phase 4b design judgment pass) ha esplicitamente identificato il problema: "`/design-review` programmatic JSON è vaporware in v3.18.0 — va prima implementato bene come release a sé". Questa release fa esattamente quello, separando la chiusura del debito dall'aggiunta di nuove feature, in modo che v3.19.0 (quando arriverà, post-dogfooding) possa appoggiarsi a un contratto programmatic stabile invece di costruirsi sopra una stub.
+
+### Fixed — `/design-review` dual-mode reale (Markdown ↔ JSON)
+
+- **[framework/.claude/commands/design-review.md](framework/.claude/commands/design-review.md) riscritto** (frontmatter invariato, body completamente sostituito). Quattro sezioni nuove + workflow rivisto:
+  - **§ Invocation Modes**: documenta esplicitamente Mode A (interactive, Markdown — il comportamento storico) e Mode B (programmatic, JSON-only — il nuovo contratto). L'envelope JSON di input per Mode B è specificato verbatim: `{mode, card_id, route, viewport, dev_server_port, registry_paths: {index, tokens, components_dir}, ui_guidelines_path, features: {has_design_system, multi_tenant_theming}, tolerance}`. Il comando lo riceve passato dall'orchestratore `/e2e-review` quando Phase 4b sarà introdotta.
+  - **§ Programmatic output schema**: schema JSON di output vincolato, allineato verbatim a `framework/.claude/agents/visual-fidelity-verifier.md` § "Output Schema" per uniformità di parsing nell'aggregatore orchestratore. Campo `source: "design-review"` distingue le finding di questo command da quelle del verifier in modalità debug; i campi `findings[].severity`/`category`/`description`/`expected`/`actual`/`fix_hint`/`evidence`/`ds_drift_code`/`confidence` sono shape-identici. La deduplicazione cross-source avviene per `(route, category, ds_drift_code)` con precedenza al verifier quando duplicate (più strutturato).
+  - **§ Severity normalization (Markdown ↔ programmatic)**: tabella di mapping deterministica Blocker → `critical`, High → `major`, Medium → `minor`, Nitpick → DROP. Il drop dei Nitpick in modalità programmatic è deliberato (troppo noise per gating; restano nel report Markdown per uso interattivo).
+  - **§ Programmatic-mode category taxonomy**: enumera le 10 categorie ammesse in Mode B (`primitive-reinvented`, `primitive-missing-spec`, `token-bypass`, `component-stale`, `index-drift`, `authority-violation`, `brand-voice-drift`, `a11y-contrast`, `a11y-focus-visible`, `interactive-state-missing`) — sottoinsieme della tassonomia canonica del verifier adattato allo scope di design judgment di questo command. Categorie non in lista vanno emesse come stringhe libere in `gaps[]`, MAI come nuove categorie inventate (l'orchestratore non sa pesarle).
+  - **§ Workflow (both modes)**: passi 0–5 unificati per Mode A e Mode B, con la divergenza solo nel formato di output finale (passi 4 e 5). Mode B usa `dev_server_port` dall'envelope per costruire URL, salva screenshot in `/tmp/design-review/<route-slug>.png` per cross-reference dall'orchestratore.
+  - **§ Mode-detection contract**: regola deterministica anti-ambiguità — Mode B è triggered SOLO se l'input contiene la substring esatta `"mode": "programmatic"` (con quote, come appare nell'envelope JSON). Vietato auto-detection da contesto invocazione ("sto girando dentro a una skill") — produce silent Markdown leakage nel parser dell'orchestratore che rompe il gate. Su envelope malformato emette `{status: "error", source: "design-review", reason: "malformed_input_envelope", findings: []}` invece di fallback a Mode A (il fallback silenzioso bloccherebbe la card invece di segnalare).
+
+### Notes
+
+- **Nessun cambio framework payload oltre al command.** Nessun nuovo agente, nessuna nuova skill, nessuna nuova chiave config, nessuna modifica a `/new` o `/e2e-review`. Solo il command `/design-review` viene reso effettivamente dual-mode come annunciato in v3.18.0. `/e2e-review` non lo invoca ancora — quella connessione (Phase 4b) viene rimandata a una future release post-dogfooding, sulla base di dati reali su quanto valore aggiunge la judgment pass sopra il `visual-fidelity-verifier`.
+- **Backward compatibility totale per uso interattivo**: utenti che invocano `/design-review /merchant/dashboard` continuano a ricevere il Markdown report identico a v3.17.x e prima. Mode A è il default; Mode B è opt-in via envelope JSON esplicito.
+- **Severity taxonomy in lockstep**: il body del command include una nota esplicita "quando aggiorni la taxonomy qui, aggiorna in lockstep `framework/.claude/agents/visual-fidelity-verifier.md` § Severity Taxonomy". Le due fonti restano allineate per evitare drift cross-source nell'aggregatore.
+- **Versioning rationale.** PATCH (3.18.0 → 3.18.1): no new capability. Il contratto Mode B era già annunciato in v3.18.0; questa release rende l'annuncio reale. Decision tree CLAUDE.md: "Doc fix, script bugfix, perf, security patch with no behaviour change → PATCH" — qualifica perché la behavior change è solo per chi sta ancora costruendo l'integrazione (nessun consumer esistente la invoca programmatically oggi).
+- **Verification** (manuale, no test suite): (1) `/design-review /merchant/dashboard` interattivo → Markdown identico al pre-3.18.1 (regression check Mode A); (2) input contenente `"mode": "programmatic"` → JSON-only output, no preamble, parsable da `JSON.parse()`; (3) envelope malformato → emette `{status: "error", reason: "malformed_input_envelope"}` senza fallback a Markdown; (4) campi `route`/`dev_server_port` mancanti dall'envelope → stesso errore; (5) finding di severity Nitpick → presente in Mode A, assente da Mode B `findings[]`.
+- **Path post-3.18.1**: dogfooding di v3.18.0 + 3.18.1 per 1–2 settimane su feature UI reali. Sulla base di falsi positivi/negativi raccolti, decidere data-driven quali estensioni includere in v3.19.0 tra: multi-viewport (mobile/desktop/tablet), interactive states (hover/focus/active/disabled + opt-in loading/empty/error), Phase 4b design judgment pass che invoca `/design-review` in Mode B all'interno di `/e2e-review`. L'adversarial review ha esplicitamente sconsigliato il bundle v3.19.0 senza dati di dogfooding — questa release rispetta quella raccomandazione.
+
+## [3.18.0] - 2026-05-25
+
+The end-to-end review fase post-implementazione diventa un **gate deterministico e BLOCKING** invece di un assortimento di check advisory. Until v3.17.x, la chiusura di una card via `/new` attraversava tre fasi eterogenee tutte non-bloccanti sul fronte UI: Phase 2.5 (Implementation Completeness Check) validava solo card AC / PRD alignment / code quality / schema / artifacts senza alcun gate visivo o funzionale runtime; Phase 2.6 (E2E Testing) era *condizionale* (solo con `test_plan.e2e_required: true` o QA profile BALANCED/DEEP) e invocava `qa-sentinel` che per charter (`qa-sentinel.md:151-161`) esegue solo gate meccanici (lint/type/test/build/audit) — non test browser-based né design; Phase 2.7 (Visual Design Review) invocava `ui-expert` ma era esplicitamente marcata "advisory, non-blocking" (`new/SKILL.md:897` — "findings logged but do NOT block commit"). Le skill `webapp-testing` e `playwright-skill` esistevano ma non erano mai auto-invocate da `/new`. La routine `ds-drift` (`framework/routines/ds-drift.routine.yml`) girava settimanalmente, catturando il drift visivo 1–7 giorni dopo il merge. **Conseguenza concreta** lamentata dall'utente: doveva rifare manualmente la review schermata-per-schermata di ogni card UI, e i dettagli grafici dei mockup venivano regolarmente ignorati.
+
+Questo release risolve il problema con un **HYBRID architecture** validata da advisor: nuova skill orchestratore `/e2e-review` + nuovo agente specializzato `visual-fidelity-verifier`, integrazione BLOCKING in `/new` Phase 2.6 (unificando 2.6 + 2.7 attuali), gating tunabile via `features.e2e_review.*`, con riuso massimo dell'esistente (`coder` per scrivere `.spec.ts`, `playwright-skill` per esecuzione, `webapp-testing` per ispezione runtime in compliance-only, `/design-review` esteso a output JSON, `ui-expert` cascade riusata in compliance-only mode). L'architettura segue il **three-layer harness pattern** documentato da Anthropic in [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents): implementer (`coder`) e verifier (`visual-fidelity-verifier`) sono distinti, con aggregazione rule-based in mezzo — nessun agente valuta il proprio lavoro. Il pattern **Definition of Done machine-readable** ([Policy Cards, arXiv 2510.24383](https://arxiv.org/abs/2510.24383)) guida la sintesi Gherkin del piano di verifica. La combo **Playwright MCP + Vision** ([Playwright MCP](https://playwright.dev/mcp/introduction), [Giving Claude Code Eyes — round-trip screenshot testing](https://medium.com/@rotbart/giving-claude-code-eyes-round-trip-screenshot-testing-ce52f7dcc563)) è il pattern canonico 2025–2026 per browser+vision in agentic dev.
+
+### Added — Nuova skill `/e2e-review` (orchestratore BLOCKING)
+
+- **Nuova skill [framework/.claude/skills/e2e-review/SKILL.md](framework/.claude/skills/e2e-review/SKILL.md)** (~530 righe). Sei fasi sequenziali:
+  - **Phase 1 — Verification Plan Extraction**: legge `card.acceptance_criteria[]`, `card.test_plan` (quando presente, schema compatibile con quello già scritto da `/prd` Step 6, senza modifiche al PRD), `card.requirements[]`, `card.links.design[]`, `card.scope.routes[]` (con fallback derivato dal diff via `codebase-architect`). Sintetizza scenari Gherkin (Given/When/Then) e li persiste in `.baldart/e2e-review/<CARD-ID>/plan.json` come contratto machine-readable consumato dalle fasi successive.
+  - **Phase 2 — Mockup Source Cascade (4 livelli)**: (a) URL Figma + Figma MCP runtime probe → `get_design_context` + `get_screenshot`; (b) path locale referenziato in `card.links.design[]` (PNG/JPG/PDF — PDF estratto con `pdftoppm`, degrada gracefully); (c) no mockup ma `features.has_design_system: true` → modalità **compliance-only** che riusa la cascade BLOCKING del [design-system-protocol.md](framework/agents/design-system-protocol.md) (INDEX.md + tokens-reference.md + components/<Name>.md); (d) nulla → skip visual + warning in `gaps[]`, functional E2E continua comunque. Nessun hard fail per assenza di Figma — la dipendenza è genuinamente opzionale.
+  - **Phase 3 — Functional E2E**: spawn `coder` con contratto preciso (file in `${paths.e2e_tests_dir}/<CARD-ID-slug>.spec.ts`, screenshot path fissato a `.baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>.png` per consumo da Phase 4, no chromium.launch, no edit fuori `${paths.e2e_tests_dir}`). Esegue `npx playwright test --reporter=json` headless in modalità programmatica (headed riservato a flussi OTP in invocazione manuale). Mappa scenari falliti in finding funzionali con severity rule-based (auth/payments/data-mutation = Critical; display-only = Major; flaky-passed-on-retry = Minor + `confidence: low`).
+  - **Phase 4 — Visual Fidelity**: pre-filter con pixel-diff (`pixel_diff_threshold` configurabile, default `0.02`) prima di invocare Vision — quando la diff è sotto soglia, il route passa senza spendere token Vision (primary latency/cost saver). Sopra soglia o in compliance-only, spawn `visual-fidelity-verifier` con payload strutturato; deduplicazione findings per `(route, category, region)`.
+  - **Phase 5 — Aggregation + Strict Severity Gate**: combina functional + visual findings, applica filtro tolerance (`strict` default → Critical+Major+Minor block; Minor con `confidence: low` auto-demote ad advisory — escape hatch documentato contro font-rendering false positive). Self-heal loop bounded (`max_self_heal_iterations`, default `2`): re-spawn `coder` con findings come fix instructions, re-esegui Phase 3+4, re-decidi. Override path: dopo esaurimento iterazioni in modalità manuale chiede reason obbligatoria (`require_override_reason: true`); in modalità programmatica restituisce `verdict: "blocked"` lasciando la decisione a `/new`.
+  - **Phase 6 — Return Protocol**: scrive `.baldart/e2e-review/<CARD-ID>/report.json` con schema strutturato `{status, iterations, findings[], ds_drift_codes[], gaps[], override_reason, transcript_paths[]}`. Modalità manuale renderizza anche Markdown summary; programmatica emette solo JSON come messaggio finale (parsato direttamente da `/new`).
+- **Gate di skip pre-flight** per evitare overhead inutile: skill REFUSES quando `features.has_e2e_review: false` (preserva backward compat); auto-skip quando card non ha `links.design` E `git diff` non mostra file UI (`.tsx`/`.css`/`.scss`/`.svelte`/`.vue` sotto `${paths.app_dir}` o `${paths.components_primitives}`); auto-skip su card type `docs`/`chore`/`config`/`backend`/`api`/`db`/`infra`. Lo skip non è failure — `/new` procede a Phase 3 normalmente.
+- **Re-run trigger**: se `/codexreview` (Phase 3.7) modifica file sotto `${paths.app_dir}`/`${paths.components_primitives}` o qualsiasi `*.css`/`*.scss` dopo il primo run, l'orchestratore re-invoca `/e2e-review` PRIMA del commit di Phase 4. Protegge contro code-review changes che reintroducono silenziosamente drift visivo.
+
+### Added — Nuovo agente `visual-fidelity-verifier`
+
+- **Nuovo agente [framework/.claude/agents/visual-fidelity-verifier.md](framework/.claude/agents/visual-fidelity-verifier.md)** (`model: sonnet`, ~280 righe). Worker stateless multimodale invocato esclusivamente da `/e2e-review` Phase 4. Unico nuovo agente del release — l'advisor ha bocciato la creazione di un secondo `e2e-functional-verifier` perché duplicherebbe il pattern Phase 2.6 attuale (`coder` scrive `.spec.ts`, Playwright esegue).
+  - **Hard prohibitions non-negotiable**: NEVER reads application source code (anti assertion-fitting bias — antipattern documentato Meta/Capgemini 2025: LLM-generated assertions che lockano il bug come "expected behavior"), NEVER edits files, NEVER proposes architectural refactors, NEVER declares "done" o "passed" (la decisione di gate è dell'orchestratore).
+  - **Input contract strict JSON**: `{card_id, route, viewport, implementation_screenshot_path, mockup_source: {level, mockup_path | figma_node_id | design_system_index_path | tokens_reference_path | components_in_scope}, tolerance, fix_hints_enabled}`.
+  - **Severity Taxonomy canonica** (SSOT consumata anche da `/e2e-review` e `/design-review`): **Critical** (`layout-break`, `element-order`, `responsiveness-break`, `component-missing`, `component-duplicated`, `unreachable-action`) blocca in ogni tolerance; **Major** (`spacing-off-scale`, `typography-{family,weight,size,line-height}`, `color-mismatch`, `color-opacity`, `gradient-direction`, `token-bypass`, `interactive-state-missing`, `a11y-contrast`, `a11y-focus-visible`) blocca in strict+balanced, advisory in lenient; **Minor** (`border-radius-off`, `shadow-off`, `micro-misalignment`, `font-rendering-variance`) blocca solo in strict (con auto-demote `confidence: low` ad advisory anche in strict).
+  - **Output schema strict JSON**: `{status, route, mockup_source_level, viewport, compliance_score, findings: [{severity, category, description, expected, actual, fix_hint, evidence: {region, screenshot_crop_path}, ds_drift_code, confidence}], ds_drift_codes[], gaps[], transcript_path}`. Citazioni token rigorose (mai paraphrase — `--color-action-primary` non "the primary blue"). Anti-hallucination discipline (no finding emessi senza evidenza visibile; `status: error` invece di guessing quando screenshot insufficiente).
+  - **Mockup source cascade behaviour**: in modalità `figma`/`local` il mockup è ground truth visuale; in `compliance-only` riusa la cascade BLOCKING del [design-system-protocol.md](framework/agents/design-system-protocol.md) (INDEX + tokens-reference + per-component specs) e mappa findings ai drift code canonici `DS_TOKENS_DRIFT`/`DS_COMPONENT_STALE`/`DS_INDEX_DRIFT` (definiti nel protocollo, non qui — un solo SSOT).
+
+### Added — Schema config propagation (regola interna del repo)
+
+- **Template [framework/templates/baldart.config.template.yml](framework/templates/baldart.config.template.yml)**: aggiunto `features.has_e2e_review: false` (default opt-in esplicito — backward compatibility totale) e nuova sezione top-level `e2e_review:` con 4 chiavi commentate. La chiave esistente `paths.e2e_tests_dir` è ora consumata anche da `e2e-review` oltre che da `playwright-skill`.
+- **`features.e2e_review` tuning sub-section**: `fidelity_tolerance` (`strict` default — Critical+Major+Minor block con escape hatch low-confidence; `balanced` blocca Critical+Major; `lenient` solo Critical), `max_self_heal_iterations` (default `2`, allineato a Phase 2.5 retry policy in `new/SKILL.md:699`), `pixel_diff_threshold` (default `0.02`, range 0.0–1.0 — pre-filter pixel-diff per skippare la Vision call quando implementazione e mockup sono pixel-identici), `require_override_reason` (default `true` — la reason loggata in tracker `## Issues & Flags` e in `report.json`).
+- **[src/commands/configure.js](src/commands/configure.js)** prompt + status: aggiunto `has_e2e_review` al loop dei feature prompt (linea ~563 nuovo); nuova sezione "E2E review tuning" prima della sezione LSP (linea ~624 nuovo) che gating su `has_e2e_review: true` chiede via `UI.select` la tolerance e poi le 3 chiavi nested; aggiunta riga "E2E review:" nel box AUTODETECTED. Il detector schema-drift in `update.js` (linee 462–503) cattura automaticamente la nuova chiave `features.has_e2e_review` via template scan generico — nessun cambio dedicato necessario. `doctor.js` `configSchemaDrift()` (linee 70–82) usa lo stesso meccanismo.
+- **[framework/AGENTS.md](framework/AGENTS.md)** tabella MUST aggiornata (linea 18): aggiunta riga `E2E review BLOCKING gate (Phase 2.6 of /new invokes /e2e-review) | features.has_e2e_review: true`.
+
+### Changed — `/new` Phase 2.6 unificata e BLOCKING
+
+- **[framework/.claude/skills/new/SKILL.md](framework/.claude/skills/new/SKILL.md) linee 814–901**: sostituite integralmente la legacy Phase 2.6 (E2E Testing condizionale invocante `qa-sentinel`) e Phase 2.7 (Visual Design Review advisory invocante `ui-expert`) con una singola Phase 2.6 unificata "End-to-End Review (BLOCKING, since v3.18.0)" che invoca `/e2e-review` in modalità programmatica. Il gate documentato sostituisce il branching condizionale precedente (`test_plan.e2e_required` + QA profile + legacy fallback heuristic): 3 condizioni di skip (feature disabled / backend-only card / docs|chore|config card), payload JSON strutturato all'invocazione, contract di ritorno JSON parsato programmaticamente. Mapping verdict→azione: `passed`/`skipped`/`overridden` → procede; `blocked` STOPpa la card senza procedere a Phase 3 e chiede all'utente override/escalation/abandon; `error` chiede retry/skip/abandon. Re-run trigger dopo Phase 3.7 `/codexreview` se file UI modificati. Tracker output strutturato per audit cross-card.
+
+### Changed — `/design-review` command estensione output JSON
+
+- **[framework/.claude/commands/design-review.md](framework/.claude/commands/design-review.md)** prologo: aggiunta nota di invocazione che documenta il dual-mode. Interactive (default) produce Markdown report (Blockers/High/Medium/Nitpicks) come oggi; programmatic mode (input contiene `"mode": "programmatic"`) ritorna un singolo JSON object matching lo schema di `visual-fidelity-verifier` per gating dell'orchestratore. Nessuna logica nuova nel command body — solo flag di output format. Permette al `/e2e-review` skill di riusare `/design-review` come tooling alternativo quando appropriato senza duplicare la cascade design-system.
+
+### Changed — Documentazione integrazione skill tooling
+
+- **[framework/.claude/skills/playwright-skill/SKILL.md](framework/.claude/skills/playwright-skill/SKILL.md)**: nuova sezione "E2E Review Integration (since v3.18.0)" prima di Quick Reference. Documenta il contratto consumer: spec generata da `coder` partendo da `plan.json`, screenshot path fissato per consumo da Phase 4, headless in modalità programmatica, mapping severity di scenari falliti. Nessuna logica nuova nella skill — solo documentazione del nuovo consumer.
+- **[framework/.claude/skills/webapp-testing/SKILL.md](framework/.claude/skills/webapp-testing/SKILL.md)**: nuova sezione "E2E Review Integration (since v3.18.0)" in testa. Documenta l'uso in compliance-only mode (cascade level c) per fetch dei computed style runtime quando manca mockup-as-image; ruolo del server lifecycle helper. Nessuna logica nuova.
+- **[framework/.claude/skills/prd/assets/card-template.yml](framework/.claude/skills/prd/assets/card-template.yml)** linea 134 ca.: aggiunto commento sopra `test_plan:` che documenta il nuovo dual consumer (`/new` legacy fallback + `/e2e-review` Phase 1 — il mapping verso Gherkin scenarios). Nessuna modifica allo schema PRD; le card scritte prima della v3.18.0 sono pienamente compatibili (Phase 1 di `/e2e-review` ha fallback da `acceptance_criteria` quando `test_plan` manca).
+
+### Changed — Registry e routing
+
+- **[framework/.claude/agents/REGISTRY.md](framework/.claude/agents/REGISTRY.md)**: aggiunta riga per `visual-fidelity-verifier` immediatamente sotto `ui-expert` (sezione Design). Specializzazione: visual diff, severity taxonomy, design-system compliance via registry cascade. Auto-invoke yes via `/e2e-review` — non spawnabile ad-hoc (l'orchestratore è il solo entry point).
+
+### Changed — Documentation utente
+
+- **[README.md](README.md)**: agent count aggiornato da 24 a 27 (visual-fidelity-verifier + numerazione resa coerente Design&UX→Specialized); skill count da 24 a 25 (e2e-review aggiunto sotto "Code quality"); nuova sezione "End-to-End Review BLOCKING Gate (new in v3.18.0)" prima della sezione "UI Excellence + Post-Intervention Coherence Gate (v3.12.0)" che riassume l'intera architettura, citando le fonti del 2025–2026 e documentando il tuning `e2e_review.*`.
+- **[framework/docs/PROJECT-CONFIGURATION.md](framework/docs/PROJECT-CONFIGURATION.md)**: tabella paths aggiornata (e2e_tests_dir ora cita anche e2e-review); nuova sezione "§ 4.2.1 `e2e_review` — tuning for the BLOCKING end-to-end review gate (v3.18.0+)" che documenta ogni chiave con tipo/default/effetto e citazioni cross-reference al protocollo `design-system-protocol.md` per i drift code.
+
+### Notes
+
+- **Backward compatibility totale.** Il default `features.has_e2e_review: false` significa che progetti pre-3.18.0 non vedono nessun cambio di comportamento finché non eseguono `npx baldart configure` (che proporrà la nuova feature) o editano manualmente la config. `/new` Phase 2.6 silenziosamente skippa la chiamata a `/e2e-review` quando il flag è false, preservando il workflow legacy con un breve log informativo nel tracker. Le card scritte prima della v3.18.0 (senza `test_plan` block, o con `test_plan.e2e_required: false`) sono pienamente supportate dalla nuova fase: Phase 1 di `/e2e-review` deriva Gherkin scenarios direttamente da `acceptance_criteria` quando `test_plan` è assente, e la mockup cascade degrada gracefully a compliance-only / skip quando `links.design` manca.
+- **Riuso massimo, footprint minimo.** Un solo nuovo agente (`visual-fidelity-verifier`) e una sola nuova skill (`/e2e-review`). Riusati: `coder` (scrittura `.spec.ts` + self-heal loop), `playwright-skill` (esecuzione spec), `webapp-testing` (compliance-only computed styles fetch), `codebase-architect` (mapping route→file fallback), `/design-review` command (esteso a output JSON per gating), `ui-expert` cascade (referenziata da `visual-fidelity-verifier` in compliance-only mode), `design-system-protocol.md` (SSOT della cascade BLOCKING e dei drift code — referenziato, mai duplicato), `ds-drift` routine (resta safety net settimanale per edit umani che bypassano `/new`). Bocciata da advisor la creazione di un secondo agente `e2e-functional-verifier` (avrebbe duplicato il pattern Phase 2.6 attuale) e di un terzo "evaluator" three-agent-harness completo (overkill quando l'aggregazione è rule-based su severity strutturata, da introdurre solo se dogfooding rivela troppi falsi positivi).
+- **Dependency contract.** Il consumer deve avere `@playwright/test` installato e `paths.e2e_tests_dir` valorizzato; lo skill rileva il gap in Phase 3 step 1 e fornisce setup hint actionable (`npm i -D @playwright/test && npx playwright install chromium`). Figma MCP è opzionale — la cascade Phase 2 degrada a level (b)/(c)/(d) senza errori. Vision usage è governata dal `pixel_diff_threshold` pre-filter — la maggior parte dei route passa senza spendere token Vision.
+- **Override path con audit trail.** Quando self-heal esaurisce iterazioni in modalità manuale e l'utente vuole comunque procedere, una reason è obbligatoria (`require_override_reason: true` default). La reason è loggata sia nel `/tmp/batch-tracker-<FIRST-CARD-ID>.md` come `[E2E-OVERRIDE] <reason>` sia in `.baldart/e2e-review/<CARD-ID>/report.json` come campo `override_reason`. Il rationale: il gate deve essere strict per default ma deve avere una via di fuga documentata — gate troppo rigidi senza escape hatch generano user override fatigue e perdita di fiducia (failure mode documentato).
+- **Re-run automatico dopo `/codexreview`.** Se Phase 3.7 modifica file UI, `/e2e-review` re-esegue PRIMA del commit di Phase 4. Lo state directory `.baldart/e2e-review/<CARD-ID>/` viene riusato (no re-fetch mockup, no re-build plan) — solo Phase 3 (functional) + Phase 4 (visual) vengono ri-eseguite. Protezione contro la classe di bug dove il code-review introduce silenziosamente drift visivo per "consistency cleanup".
+- **Verification è manuale (no test suite — `npm test` resta no-op stub).** Dogfood scenarios da girare dopo l'install:
+  1. `npx baldart configure` su progetto pre-3.18.0 → la propagazione schema drift detector cattura `features.has_e2e_review` mancante e offre `configure` automaticamente. Il prompt "Enable BLOCKING end-to-end review?" appare; rispondendo `Yes` la sezione "E2E review tuning" chiede tolerance/max-iter/threshold/require-reason.
+  2. `/e2e-review CARD-ID` manuale su una card UI esistente con `features.has_e2e_review: true` + `links.design` valorizzato → il piano viene scritto in `.baldart/e2e-review/<CARD-ID>/plan.json`, il `.spec.ts` generato in `tests/e2e/`, screenshot scattate, `visual-fidelity-verifier` invocato per ogni route, report JSON + Markdown summary mostrato all'utente.
+  3. `/new <CARD-ID>` su card UI dopo opt-in → Phase 2.6 invoca `/e2e-review` programmatically; verdict `passed` procede a Phase 3 normalmente; verdict `blocked` STOPpa la card e chiede override/escalation/abandon all'utente.
+  4. `/new <CARD-ID>` su card backend-only (no `links.design`, no file UI nel diff) → Phase 2.6 auto-skip con log `"e2e-review: SKIP (backend-only card)"`, procede a Phase 3 senza errori.
+  5. Test sintetico iniettivo: card con 3 deviazioni note pre-iniettate (colore button hardcoded, padding fuori scala token, border-radius literal) → report contiene esattamente 3 finding con severity (Major, Major, Minor in strict mode) e gate blocca il commit.
+  6. Negative path Figma MCP non disponibile → cascade falls through a level (b) (immagine locale) o (c) (compliance-only) senza hard fail; warning loggato in `gaps[]`.
+  7. Self-heal loop: card con token bypass fixabile → il loop converge in ≤ 2 iterazioni e il commit procede senza override richiesto.
+  8. Override path: card con falso positivo evidente → l'utente fornisce reason, commit procede con `[E2E-OVERRIDE] <reason>` loggato nel tracker e in `report.json`.
+- **Versioning rationale.** Impact MINOR (3.17.1 → 3.18.0): aggiunge una skill (`/e2e-review`), un agente (`visual-fidelity-verifier`), una fase BLOCKING nella skill esistente `/new`, e nuove chiavi di configurazione (`features.has_e2e_review` + sub-section `e2e_review.*`). Non rompe installazioni esistenti — il default `false` mantiene il comportamento legacy fino a opt-in esplicito via `configure`. Non rimuove agenti / cambia layout di directory / cambia comandi CLI (decision tree MAJOR non si applica).
+
 ## [3.17.1] - 2026-05-23
 
 CLI quality-of-life patch shaken loose by a hands-on consumer update simulation (mayo, 3.13.0 → 3.16.0). Four real bugs surfaced when actually driving `baldart update` end-to-end from a scripted context. Two were show-stoppers for any non-interactive use (CI, AI-driven, headless update agent), one was cosmetic but ugly, one was a stale stub that lied to the user. All four are fixed; nothing in this release changes framework payload behaviour for end-users running BALDART interactively in a TTY.

package/README.md

@@ -85,7 +85,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 - **agents/**: 17 domain modules (architecture, workflows, testing, security, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
-### AI Agents (24 specialized agents)
+### AI Agents (27 specialized agents)
 
 **Core (required for every project)**
 1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
@@ -107,19 +107,20 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 15. **motion-expert**: Animation specs, transitions, micro-interactions
 16. **hyper-gamification-designer**: Game mechanics, retention loops, economy balance
 17. **remotion-animator-orchestrator**: Video/motion graphics with Remotion
+18. **visual-fidelity-verifier** (v3.18.0): Stateless multimodal worker auto-invoked by `/e2e-review` Phase 4 — compares an implemented UI route against its mockup (or design-system spec) and returns a severity-tagged JSON report. Never reads source code (anti assertion-fitting bias), never edits, never declares done
 
 **Product & Marketing**
-18. **onboarding-architect-lead**: User onboarding flow design and experimentation
-19. **marketing-conversion-strategist**: High-converting copy and messaging
-20. **seo-analytics-strategist**: SEO strategy, metadata, GA4/GTM event planning
-21. **email-deliverability-architect**: Transactional/informational email design + SPF/DKIM/DMARC
-22. **website-orchestrator**: Multi-agent website development coordination
+19. **onboarding-architect-lead**: User onboarding flow design and experimentation
+20. **marketing-conversion-strategist**: High-converting copy and messaging
+21. **seo-analytics-strategist**: SEO strategy, metadata, GA4/GTM event planning
+22. **email-deliverability-architect**: Transactional/informational email design + SPF/DKIM/DMARC
+23. **website-orchestrator**: Multi-agent website development coordination
 
 **Specialized**
-23. **hybrid-ml-architect**: ML/DL system design (recommenders, ranking, embeddings)
-24. **legal-counsel-gdpr**: GDPR compliance, privacy policies, data governance
-25. **deep-human-insight**: Psychological / sociological analysis for B2C UX and adoption
-26. **skill-improver**: Weekly auto-improvement of skills/agents based on review/QA findings
+24. **hybrid-ml-architect**: ML/DL system design (recommenders, ranking, embeddings)
+25. **legal-counsel-gdpr**: GDPR compliance, privacy policies, data governance
+26. **deep-human-insight**: Psychological / sociological analysis for B2C UX and adoption
+27. **skill-improver**: Weekly auto-improvement of skills/agents based on review/QA findings
 
 REGISTRY.md is the single source of truth for agent routing and capabilities.
 
@@ -207,13 +208,13 @@ Skills always-ask when required keys are missing — never silently default.
 never overwrites your file. Full guide:
 [`framework/docs/PROJECT-CONFIGURATION.md`](framework/docs/PROJECT-CONFIGURATION.md).
 
-### Skills (24 portable skills)
+### Skills (25 portable skills)
 
 Skills live under `.claude/skills/` and are auto-discovered by Claude Code.
 Bundled skills:
 
 - **Workflow**: `new`, `prd`, `prd-add`, `bug`, `simplify`, `worktree-manager`, `issue-review`, `context-primer`
-- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0)
+- **Code quality**: `skill-creator`, `find-skills`, `webapp-testing`, `playwright-skill`, `lsp-bootstrap` (v3.10.0), `e2e-review` (v3.18.0)
 - **Design**: `frontend-design`, `ui-design`, `motion-design`, `gamification-design`, `design-system-init` (v3.11.0)
 - **Product**: `seo-audit`, `copywriting`, `api-design-principles`
 - **Knowledge**: `doc-writing-for-rag`, `capture` (LLM wiki overlay)
@@ -223,6 +224,14 @@ Bundled skills:
 
 When `features.has_design_system: true`, every UI-touching agent/skill/command (`ui-expert`, `ui-design`, `frontend-design`, `code-reviewer`, `/design-review`) follows the same BLOCKING cascade: read `${paths.design_system}/INDEX.md` (Authority Matrix), `tokens-reference.md` (token contract), and `components/<Name>.md` for every primitive in scope — BEFORE producing or reviewing any UI. New components must reuse from the registry or ship their per-component spec in the same change. Hardcoded color/shadow/radius/spacing values are HIGH findings. The textual SSOT for the protocol lives in [`framework/agents/design-system-protocol.md`](framework/agents/design-system-protocol.md). Projects without a registry can bootstrap one with `/design-system-init`, which inventories existing primitives, extracts tokens from global styles + Tailwind config, scaffolds the registry, and flips the flag.
 
+### End-to-End Review BLOCKING Gate (new in v3.18.0)
+
+When `features.has_e2e_review: true`, the `/new` orchestrator Phase 2.6 invokes the new `/e2e-review` skill on every UI card (auto-skipped on backend-only cards). The skill is a **deterministic, BLOCKING** orchestrator that combines functional E2E (Playwright spec written by `coder`, executed via `playwright-skill`) with visual fidelity diff (`visual-fidelity-verifier` multimodal agent) and aggregates findings under a strict severity gate. This replaces the legacy advisory pair (Phase 2.6 conditional E2E + Phase 2.7 non-blocking design review) that left the user manually re-verifying every screen.
+
+The skill walks a **4-level mockup source cascade** (Figma MCP → local PNG/JPG/PDF → design-system compliance-only → skip-with-warning) — Figma is opt-in, the framework remains portable. The aggregation gate uses a **canonical severity taxonomy** (Critical: layout/responsiveness/element-order/component-missing; Major: spacing/typography/color/token-bypass/interactive-state/a11y; Minor: border-radius/shadow/micro-misalignment). The gate enforces three pillars from the 2025–2026 agentic-testing literature: (a) **implementer ≠ verifier** ([Anthropic — Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)), (b) **Definition of Done machine-readable** ([Policy Cards, arXiv 2510.24383](https://arxiv.org/abs/2510.24383)), (c) **Playwright MCP + Vision** as the canonical browser+vision combo ([Playwright MCP](https://playwright.dev/mcp/introduction)).
+
+Tuning lives under `features.e2e_review` in `baldart.config.yml`: `fidelity_tolerance` (`strict` | `balanced` | `lenient`, default `strict`), `max_self_heal_iterations` (default `2`), `pixel_diff_threshold` (default `0.02` — pre-filter to skip Vision when implementation and mockup are pixel-identical, primary cost saver), `require_override_reason` (default `true`). When self-heal exhausts iterations, the gate exposes an **override path with mandatory reason** logged in the tracker's `## Issues & Flags` for auditability. The weekly `ds-drift` routine remains as a complementary safety net for direct human edits that bypass `/new`.
+
 ### UI Excellence + Post-Intervention Coherence Gate (new in v3.12.0)
 
 The `ui-expert` agent is upgraded from a generic baseline to a world-class UI/UX reviewer/designer — UI States Taxonomy (8 states), Performance Gates (Core Web Vitals 2026 — LCP/INP/CLS), modern CSS surface (container queries, `:has()`, View Transitions, subgrid, logical properties), AI-era patterns (streaming UI, hallucination guardrails), and 60+ categorized red flags. Numeric reference tables (type scale, contrast targets WCAG+APCA, spacing scales, density tiers, motion durations/easings) are SSOT'd in [`framework/agents/design-system-protocol.md`](framework/agents/design-system-protocol.md) so agents cite values verbatim instead of inventing them. Crucially, the registry-first discipline now has a **post-intervention coherence gate**: every UI change introduced by `ui-expert` / `ui-design` / `frontend-design` (and verified by `code-reviewer` at merge) must reconcile `INDEX.md` + `components/<Name>.md` + `tokens-reference.md` **in the same change** — drift can no longer wait for the weekly `ds-drift` routine. Three layers now enforce coherence: per-task → per-merge → weekly safety net. Existing projects align their current graphic organization with the new discipline via [`framework/docs/UPGRADE-3.12-UI-COHERENCE.md`](framework/docs/UPGRADE-3.12-UI-COHERENCE.md) (idempotent walkthrough: baseline scan → prioritized backlog → quick wins → gate verification).

package/VERSION

@@ -1 +1 @@
-3.17.1
+3.18.1

package/framework/.claude/agents/REGISTRY.md

@@ -18,6 +18,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **qa-sentinel** | QA | **Mechanical gate runner** — lint, typecheck, test suite, build, security audit, markdownlint. Returns PASS/FAIL verdict only. Does NOT analyze code, verify ACs, or review security/performance (those are Phase 2.5 and code-reviewer responsibilities). | Gate execution, verdicts | No (reports failures, coder fixes) | ESLint, tsc, node --test, npm run build, npm audit, markdownlint |
 | **hybrid-ml-architect** | ML | Design/implement ML systems end-to-end | Recommender, ranking, embeddings | Yes | Model design, evaluation, monitoring |
 | **ui-expert** | Design | Design and review UI/UX | Mobile-first, accessibility, registry-first protocol gate (when `features.has_design_system: true`) — BLOCKING reads on `${paths.design_system}/INDEX.md` + `tokens-reference.md` + `components/<Name>.md` per `framework/agents/design-system-protocol.md`, Component Discovery cascade before any design | No | ui-ux-pro-max, Playwright |
+| **visual-fidelity-verifier** | Design | Compare an implemented UI route against its mockup (or design-system spec) and return a severity-tagged JSON report. Auto-invoked by `/e2e-review` skill (Phase 4) — never spawned ad-hoc. Stateless. Strict severity taxonomy (Critical / Major / Minor) — never reads source code (anti assertion-fitting bias), never edits, never declares done. | Visual diff, severity taxonomy, design-system compliance check via registry cascade | No | Vision (multimodal), Read (screenshots + registry only), Playwright screenshots passed in by orchestrator |
 | **visual-designer** | Design | Generate visual assets via Kie.ai | Illustrations, icons, hero images | Yes | Kie.ai API, WebP optimization |
 | **motion-expert** | Design | Design animations and micro-interactions | Transitions, timing, easing | No | Animation specs, a11y fallbacks |
 | **hyper-gamification-designer** | Design | Analyze game features and retention mechanics | Progression, reward loops | No | MDA analysis, economy balance |

package/framework/.claude/agents/visual-fidelity-verifier.md

@@ -0,0 +1,319 @@
+---
+name: visual-fidelity-verifier
+description: "Compare an implemented UI route against its mockup (or design-system spec) and return a severity-tagged JSON report. Stateless multimodal worker invoked by the /e2e-review skill — never edits code, never reads source, never declares done. Single responsibility: visual diff."
+model: sonnet
+color: orange
+---
+
+You are the **Visual Fidelity Verifier**. You exist for one purpose: compare a
+rendered UI screenshot against its intended mockup (or, in compliance-only mode,
+against the project's design-system spec) and return a deterministic,
+severity-tagged JSON report.
+
+You are stateless. You do not iterate. You do not fix. You report what you see
+versus what was intended, with a structured severity tag and a fix hint per
+finding. The orchestrating skill (`/e2e-review`) decides what to do with your
+output.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:**
+`paths.design_system`, `paths.ui_guidelines`, `paths.global_styles`,
+`paths.components_primitives`, `identity.design_philosophy`,
+`features.has_design_system`, `features.e2e_review.fidelity_tolerance`,
+`features.e2e_review.pixel_diff_threshold`.
+
+**Gated by features:** `features.has_e2e_review`. The agent refuses to run
+when `false` — it exists only to support the `/e2e-review` skill.
+
+**On missing/empty keys:** report the gap in the output JSON and downgrade to
+the most degraded cascade level (skip visual + warning). Do not assume defaults.
+See `framework/agents/project-context.md` § 3.
+
+## Hard Prohibitions (non-negotiable)
+
+- **NEVER read application source code** (`.tsx`, `.ts`, `.css`, `.scss`,
+  `.jsx`, `.js` under `${paths.components_root}` or `${paths.app_dir}`). Reading
+  the implementation creates assertion-fitting bias — you would describe what
+  the code says, not what the screen shows. Antipattern documented Meta /
+  Capgemini 2025: LLM-generated assertions that lock the current bug as
+  "expected behavior".
+- **NEVER edit any file.** You produce a JSON report only. The orchestrator
+  delegates fixes to a separate `coder` agent in a self-heal loop.
+- **NEVER propose architectural refactors.** Your scope is visual fidelity, not
+  component API design (that is `ui-expert`'s job).
+- **NEVER declare a task "done" or "passed".** You return findings. The strict
+  gate logic lives in the `/e2e-review` skill — it decides pass/block/override.
+
+## Input Contract
+
+The orchestrator (`/e2e-review`) invokes you with this JSON payload:
+
+```json
+{
+  "card_id": "FEAT-XXXX",
+  "route": "/merchant/dashboard",
+  "viewport": { "width": 1440, "height": 900 },
+  "implementation_screenshot_path": "/abs/path/to/impl.png",
+  "mockup_source": {
+    "level": "figma" | "local" | "compliance-only" | "skip",
+    "mockup_path": "/abs/path/to/mockup.png",   // present for figma + local
+    "figma_node_id": "1:23",                      // present for figma
+    "design_system_index_path": "...",            // present for compliance-only
+    "tokens_reference_path": "...",               // present for compliance-only
+    "components_in_scope": ["Button","Card"]      // present for compliance-only
+  },
+  "tolerance": "strict" | "balanced" | "lenient",
+  "fix_hints_enabled": true
+}
+```
+
+If `mockup_source.level == "skip"`, return immediately with
+`{ "status": "skipped", "reason": "no_mockup_available", "findings": [] }`.
+
+## Severity Taxonomy (CANONICAL — cite verbatim)
+
+This taxonomy is the SSOT consumed by `/e2e-review` and `/design-review`. Do
+not invent new severity levels. Do not move categories across tiers.
+
+### Critical (BLOCKS in any tolerance — strict, balanced, lenient)
+
+| Category | Examples |
+|---|---|
+| `layout-break` | Flexbox/grid container collapsed, elements stacked when designed side-by-side, vertical rhythm broken |
+| `element-order` | DOM/visual order differs from mockup (Button placed before Title when designed after) |
+| `responsiveness-break` | Breakpoint missing — desktop layout served on 320–375px viewport, horizontal scroll on mobile |
+| `component-missing` | Designed component absent from rendered output (e.g. mockup has a CTA card, screen does not) |
+| `component-duplicated` | Same primitive rendered twice when designed once (e.g. accidental React key collision) |
+| `unreachable-action` | Primary CTA off-screen / behind fixed overlay / unreachable by thumb on mobile |
+
+### Major (BLOCKS in strict + balanced; advisory in lenient)
+
+| Category | Examples |
+|---|---|
+| `spacing-off-scale` | Padding/margin outside the token scale (e.g. `padding: 13px` instead of `--space-3 = 12px`) |
+| `typography-family` | Font-family differs from design (e.g. system-ui rendered, Inter designed) |
+| `typography-weight` | Font-weight off (400 rendered, 600 designed) |
+| `typography-size` | Font-size off (16px rendered, 18px designed) AND outside the type-scale tolerance (> 2px diff) |
+| `typography-line-height` | Line-height outside the spec (1.5 rendered, 1.35 designed for heading) |
+| `color-mismatch` | Hex / oklch off by more than the perceptual delta (delta-E > 2 for body, > 1 for brand surface) |
+| `color-opacity` | Alpha channel off (e.g. 100% rendered, 80% designed) |
+| `gradient-direction` | Gradient angle / stops off |
+| `token-bypass` | Implementation uses a hardcoded value where the project's token would apply (detectable in compliance-only mode via tokens-reference cross-check) |
+| `interactive-state-missing` | Hover / focus / active / disabled state absent or visually identical to idle |
+| `a11y-contrast` | Body text contrast < 4.5:1 (WCAG AA) or < APCA Lc 75; focus indicator < 3:1 |
+| `a11y-focus-visible` | Interactive element has `outline: none` without equivalent custom focus indicator |
+
+### Minor (BLOCKS only in strict tolerance; logged elsewhere)
+
+| Category | Examples |
+|---|---|
+| `border-radius-off` | Radius differs by 1–2px or uses literal instead of token (e.g. `border-radius: 7px` vs `--radius-md = 8px`) |
+| `shadow-off` | Shadow blur/spread off by < 4px or uses literal instead of token |
+| `micro-misalignment` | Element offset by 1–2px from designed position (sub-grid drift) |
+| `font-rendering-variance` | Anti-aliasing / subpixel rendering difference (often a false positive — flag with low confidence) |
+
+## Mockup Source Cascade Behavior
+
+You receive `mockup_source.level` from the orchestrator. Adapt your protocol:
+
+### Level (a) — `figma`
+
+Mockup is a Figma frame screenshot fetched via the Figma MCP server.
+`mockup_path` is the local PNG, `figma_node_id` is the Figma node identity for
+audit trail. Treat the Figma frame as the **ground truth** — the implementation
+must match it modulo the tolerance thresholds below.
+
+### Level (b) — `local`
+
+Mockup is a local image (PNG / JPG / PDF first page) referenced in
+`card.links.design`. Same protocol as Figma — local image is ground truth.
+
+### Level (c) — `compliance-only`
+
+No image-based mockup is available, but `features.has_design_system: true`. You
+do NOT diff against a picture. Instead, execute the **registry-first cascade**
+defined in [`framework/agents/design-system-protocol.md`](../../agents/design-system-protocol.md)
+§ "BLOCKING pre-work":
+
+1. Read `${paths.design_system}/INDEX.md` and extract the Authority Matrix for
+   the components in scope.
+2. Read `${paths.design_system}/tokens-reference.md` to know which color /
+   spacing / shadow / radius / motion values are canonical.
+3. For each component in `mockup_source.components_in_scope`, read
+   `${paths.design_system}/components/<Name>.md`.
+
+Then inspect the implementation screenshot and flag:
+
+- **token-bypass** — colors / spacings / shadows / radii in the rendered UI
+  that do not match any token in `tokens-reference.md`. Reuse the drift codes
+  from `design-system-protocol.md` § "Post-Intervention Coherence Check":
+  `DS_TOKENS_DRIFT`.
+- **component-stale** — primitives that differ from their spec
+  (`DS_COMPONENT_STALE`).
+- **index-drift** — primitives rendered that are not in `INDEX.md`
+  (`DS_INDEX_DRIFT`).
+
+In compliance-only mode you also work from the rendered screenshot, but the
+ground truth is the registry + tokens, not an image. Output schema is the same
+(findings array + ds_drift_codes).
+
+### Level (d) — `skip`
+
+Return immediately with `{ "status": "skipped", "reason":
+"no_mockup_available", "findings": [] }`. Do not attempt to invent fidelity
+checks without a ground truth.
+
+## Tolerance Modes
+
+The orchestrator passes `tolerance` from `features.e2e_review.fidelity_tolerance`:
+
+- **`strict`** (default) — Critical + Major + Minor findings are all reported
+  with their canonical severity. The orchestrator will BLOCK on any of them.
+- **`balanced`** — Same reporting; the orchestrator will block on Critical +
+  Major only, Minor are advisory.
+- **`lenient`** — Same reporting; the orchestrator blocks on Critical only.
+
+Your job is unchanged across modes: **always report every finding with its
+canonical severity**. Filtering is the orchestrator's responsibility, not yours.
+Inflating or suppressing severity to match the mode is a protocol violation.
+
+## Output Schema (STRICT — orchestrator parses programmatically)
+
+```json
+{
+  "status": "completed" | "skipped" | "error",
+  "route": "/merchant/dashboard",
+  "mockup_source_level": "figma" | "local" | "compliance-only" | "skip",
+  "viewport": { "width": 1440, "height": 900 },
+  "compliance_score": 0.87,
+  "findings": [
+    {
+      "severity": "critical" | "major" | "minor",
+      "category": "spacing-off-scale",
+      "description": "Card padding rendered at 13px; mockup specifies 12px (token --space-3).",
+      "expected": "padding: 12px",
+      "actual": "padding: 13px",
+      "fix_hint": "Replace literal `padding: 13px` with the spacing token `--space-3` (resolves to 12px in tokens-reference.md). Likely location: components/Card.tsx.",
+      "evidence": {
+        "region": { "x": 240, "y": 180, "w": 320, "h": 200 },
+        "screenshot_crop_path": "/tmp/e2e-review/FEAT-0500/critical-1.png"
+      },
+      "ds_drift_code": "DS_TOKENS_DRIFT" | "DS_COMPONENT_STALE" | "DS_INDEX_DRIFT" | null,
+      "confidence": "high" | "medium" | "low"
+    }
+  ],
+  "ds_drift_codes": ["DS_TOKENS_DRIFT"],
+  "gaps": [
+    "no Figma MCP available — fell back to local image mode",
+    "no spec found for primitive `Badge` — could not check component conformance"
+  ],
+  "transcript_path": "/tmp/e2e-review/FEAT-0500/visual-fidelity-transcript.md"
+}
+```
+
+**Field rules:**
+
+- `compliance_score` is the share of compared dimensions (layout / spacing /
+  typography / color / interactive states) that passed without findings,
+  rounded to 2 decimals. Heuristic — not a contractual metric.
+- `description` is a single sentence in English (the framework's lingua franca
+  for cross-project portability). It describes what the screen shows and what
+  the mockup says.
+- `expected` and `actual` are short token/value pairs when possible
+  (`padding: 12px` / `padding: 13px`), or a 1-line natural description when
+  not (`gradient from top-left to bottom-right` /
+  `gradient from top to bottom`).
+- `fix_hint` MUST be actionable: cite the token name, the likely file, or the
+  exact CSS property to change. Never "make it look right" or "match the
+  design". If you cannot produce an actionable hint, drop the finding's
+  severity by one tier (or remove it entirely if it was already Minor).
+- `evidence.region` is the bounding box in the implementation screenshot where
+  the finding occurs (`x,y,w,h` in viewport CSS pixels). Optional — include
+  when the region is unambiguous.
+- `evidence.screenshot_crop_path` is optional and only used when the
+  orchestrator pre-cropped a region of interest for you.
+- `confidence` defaults to `high`. Use `medium` when the difference is at the
+  edge of perceptual thresholds (e.g. spacing off by 1px). Use `low` for
+  rendering-variance findings (anti-aliasing, font hinting) — the orchestrator
+  may auto-filter `low`-confidence Minor findings even in strict mode.
+- `ds_drift_codes` is the deduplicated union of all `ds_drift_code` values
+  across findings (for the orchestrator's per-card drift summary).
+- `gaps` is a free-text list of context the agent wanted but did not have
+  (missing spec file, no Figma access, etc.). The orchestrator surfaces these
+  to the user.
+- `transcript_path` is optional — write a free-form markdown narrative of your
+  reasoning to this path if you want the orchestrator to surface it for human
+  review.
+
+## Comparison Protocol
+
+1. **Load inputs**. Read the implementation screenshot. If `mockup_source.level
+   in {figma, local}`, read the mockup image. If `compliance-only`, read the
+   registry files listed above. Confirm dimensions / aspect ratios.
+2. **Region-by-region scan**. Walk the implementation screenshot top-to-bottom,
+   left-to-right. For each visible primitive (header, card, button group, form,
+   list, footer, …), compare against the ground truth.
+3. **Compare structured properties first** (layout, ordering, presence of
+   designed elements) — these surface Critical findings cheaply.
+4. **Then compare typography** (family, size, weight, line-height, casing) —
+   these are the most common Major findings.
+5. **Then compare color and surfaces** (background, foreground, borders,
+   shadows, gradients) — beware of false positives from perceptual variance;
+   use `confidence: medium` when the delta is borderline.
+6. **Then compare spacing** (padding, margin, gap) — derive expected values
+   from tokens-reference when available, from the mockup pixel measurement
+   otherwise.
+7. **Then check interactive states** if the orchestrator provided
+   hover/focus/active screenshots in addition to idle.
+8. **Then check accessibility** signals visible from the screenshot
+   (contrast, focus-visible) — do not invent a11y findings you cannot see.
+9. **Compose findings** into the JSON schema above. Order findings by severity
+   (Critical → Major → Minor), then by category alphabetically within tier.
+10. **Compute `compliance_score`** as a heuristic single number. Be honest —
+    a score of 1.0 means you found nothing; a score of 0.0 means the screen
+    bears no resemblance to the mockup.
+
+## Anti-Hallucination Discipline
+
+- If you cannot tell from the screenshot whether a finding is real, do not
+  emit it. False positives erode trust in the gate and cause user override
+  fatigue — the documented failure mode.
+- When the implementation screenshot is too small / blurry / partial, return
+  `{ "status": "error", "reason": "screenshot_quality_insufficient",
+  "findings": [] }` instead of guessing.
+- When the mockup is ambiguous (e.g. low-fidelity wireframe), downgrade Minor
+  findings to advisory in the description and use `confidence: low`.
+- Cite tokens and spec entries by **exact name** as they appear in
+  `tokens-reference.md` / `components/<Name>.md`. Never paraphrase a token name
+  ("the primary blue" instead of `--color-action-primary`).
+
+## What You Are Not
+
+- You are not `ui-expert`. That agent designs and reviews UI in a creative /
+  evaluative sense (Authority Matrix, design philosophy, taste). You only
+  compare an existing rendering to an existing target.
+- You are not `qa-sentinel`. That agent runs mechanical gates (lint, tsc,
+  test, build). You do visual fidelity only.
+- You are not `code-reviewer`. That agent reviews source code for bugs and
+  quality. You do not read source code.
+- You are not the orchestrator. `/e2e-review` aggregates your findings,
+  manages the self-heal loop, and produces the final pass/block decision.
+
+## Linked Protocols
+
+- [`framework/agents/design-system-protocol.md`](../../agents/design-system-protocol.md)
+  — SSOT for the registry-first cascade and Post-Intervention Coherence Check.
+  Drift codes (`DS_INDEX_DRIFT`, `DS_COMPONENT_STALE`, `DS_TOKENS_DRIFT`) are
+  defined there.
+- [`framework/agents/design-review.md`](../../agents/design-review.md) —
+  shared design-review checklist; do not duplicate it here.
+- [`framework/agents/project-context.md`](../../agents/project-context.md) —
+  always-ask / never-assume contract for missing config keys.
+
+## Return Protocol
+
+Emit a single JSON object matching the Output Schema above as your final
+message. No prose preamble, no markdown narrative outside the optional
+`transcript_path` file. The orchestrator parses your output programmatically;
+extra prose breaks the gate.