baldart 4.77.0 → 4.78.1

package/CHANGELOG.md

@@ -5,6 +5,39 @@ 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).
 
+## [4.78.1] - 2026-06-29
+
+**`/ds-new` + `/ds-edit` now close the closed-loop (the `DS_MIRROR_STALE` nudge).** The mirror advisory — check #6 of the Post-Intervention Coherence Check, which nudges `/design-sync publish` when the in-repo registry has moved ahead of its Claude Design satellite — was cited by **every** UI-touching surface (`code-reviewer`, `ui-design`, `/design-review`, `/new` implement, `/prd` ui-design-phase, the `ds-drift` backstop) **except the two skills whose whole job is to create/modify a canonical element**: `/ds-new` and `/ds-edit`. So creating a primitive with `/ds-new` on a satellite-bound project never reminded the user to publish it — the one event that most directly makes the mirror stale was the one that skipped the nudge. This release adds the citation to both skills' step-8 coherence report.
+
+**PATCH** — doc-only completion of an existing advisory check; no new capability, no agent, **no `baldart.config.yml` key** (the check rides on the already-present `features.has_design_system` + the satellite-bound gate). The definition stays the single SSOT in `design-system-protocol.md` § Post-Intervention Coherence Check check #6 — the skills **cite, never redefine** it. Skipped when no satellite is bound (the vast majority of consumers → no-op); never blocks creation/edit.
+
+### Changed
+
+- **`/ds-new`** (`framework/.claude/skills/ds-new/SKILL.md`) — step 8 coherence report now surfaces `DS_MIRROR_STALE` (advisory, non-blocking) nudging `/design-sync publish` when a Claude Design satellite is bound (`.baldart/design-sync.json` has a `project_id`); added a `See Also` pointer to `/design-sync`.
+- **`/ds-edit`** (`framework/.claude/skills/ds-edit/SKILL.md`) — same step-8 mirror advisory, with the breaking-edit note that satellite drift is the same class as the migration; added the `/design-sync` `See Also` pointer.
+
+## [4.78.0] - 2026-06-29
+
+**Route-independent per-card mockup fidelity + graphics fast-lane.** On a `/new` run a desktop "Edit product" page shipped as **1 column** against a **2-column** mockup, marked DONE: the fidelity gate never ran on a rendered page because the auth-gated route returned 500 under the empty-Supabase demo lane, the views were "soft-skipped", and the verdict came back `ACCEPTED (harness limit)` — **a skip masked as a pass**. Two adversarial passes found this is not one bug but two distinct holes hitting two cards, plus the fact that the fidelity check depended on rendering a live, data-bearing route at all. This release inverts the priority: per-card UI fidelity is verified **route-independently, before proceeding** — a code-structural diff first, an isolated render as confirmation — and an un-runnable required check now **blocks instead of silently passing**. Bets validated against 2026 best practice (structural TED + perceptual diff as complementary dimensions; MLLM-as-judge reliable at comparison, weak at absolute scoring → fidelity gates, quality stays advisory).
+
+**MINOR** — adds an agent (`markup-fidelity-verifier`, 30→31) + capability. **No new `baldart.config.yml` key** (rides on `features.has_e2e_review` + `features.has_design_system`), so the schema-change propagation rule does NOT apply. Claude + Codex portable (the structural pass is Read-only; the image-load/isolated-render degrade to no-op where unavailable).
+
+### Added
+
+- **`markup-fidelity-verifier` agent** (`framework/.claude/agents/markup-fidelity-verifier.md`, `model: sonnet`) — the **route-independent structural twin** of `visual-fidelity-verifier`. Compares the implementation's code structure against the mockup expressed as code (`links.design` HTML or `links.design_src`/`mockups/_src/`) with no browser/auth/data — the DOM tree-edit-distance analogue, complementary to the visual verifier's pixel/perceptual diff. Deterministically catches the **2-column-mockup → 1-column-build** class of divergence. READS code (mockup-vs-impl, no assertion-fitting risk); same canonical taxonomy + JSON output; fixes route to `ui-expert`.
+- **`/e2e-review` Phase 2.7 — Structural Fidelity (route-free)** — runs the `markup-fidelity-verifier` BEFORE the browser passes, on every card with an HTML/`design_src` mockup. The workhorse of per-card fidelity.
+- **`/e2e-review` Phase 3.8 — Comparable-render gate (state-aware)** — the reviewer never accepts "opened it, it's empty, skip". Detects a degenerate render (non-2xx / empty-state / wrong tenant) and runs a bounded **reach-state loop** (overlay recipes `seed_data` / `select_populated_context` / `goto_populated_entity`, with generic fallbacks: real auth, MSW/API-mock, deterministic factory/snapshot, heuristic context auto-seek) before diffing. New `data-state-mismatch` (Critical) finding.
+- **Coverage obligation** — new `coverage-gap` (Critical) finding synthesized when an image-only mockup route could not be rendered in any lane and its state could not be reached; maps to the existing `blocked` verdict, bypasses the self-heal loop. Guards exclude `skip`/`harness-render`/`compliance-only`/mobile-pass. This turns the FEAT-0061 "skip masked as pass" into a real block.
+- **Starter overlay** `framework/templates/overlays/e2e-review.fidelity-example.md` — schema for project-specific reach-state recipes.
+
+### Changed
+
+- **`visual-fidelity-verifier`** — `coverage-gap` + `data-state-mismatch` added to the canonical severity taxonomy (SSOT); new "Data-State Awareness" rule: never compare a degenerate render, emit `data-state-mismatch` instead of a silent skip/pass.
+- **`/e2e-review` Phase 2** ingests **HTML mockups** (`links.design` `.html` → headless `file://` render to PNG for the visual pass + retained as code for the structural pass) and recognizes `links.design_src`. **Phase 5b self-heal** routes ALL fidelity fixes (structural/presentational/quality) to `ui-expert`; `coder` only for genuine wiring.
+- **`/new` graphics fast-lane** — a **pure-graphics card** (`owner_agent: ui-expert` + `review_profile: light` + `areas == [ui]` + zero Step-A triggers) skips Simplify (Phase 2.55) and per-card Codex (Phase 3.7); qa is the build/lint/tsc floor; the `/e2e-review` fidelity trio is the review. Safety net preserved by the batch-wide Final FULL Codex gate. Wired in `review-cycle.md`, `codex-gate.md`, `prd-card-writer.md` (emit `owner_agent: ui-expert` on Rule C branch-(b) cards).
+- **`/new` no cross-card fidelity deferral** — `completeness.md` Phase 2.5b Step 4 fidelity-AC carve-out: a visual-fidelity AC cannot be silently deferred ("Approva il deferral" withheld) — only implement-now (→ `ui-expert`), explicit follow-up card, or halt. `review-cycle.md` Phase 2.6: a fidelity AC closes only on a real `passed`, never a `skipped`.
+- **`design-system-protocol.md`** — new SSOT section "Route-Independent Fidelity & Coverage Obligation" (structural fidelity, visual confirmation, state-aware fidelity, coverage obligation, graphics-card rule, gating calibration) cited by `/e2e-review`, `/new`, `/design-review`.
+
 ## [4.77.0] - 2026-06-29
 
 **TS-aware design-system extractor + the `variant_prop` HEAD field.** The component-manifest extractor was pure-regex (zero-dep) and could not resolve TypeScript: a `type Variant = 'a'|'b'; variant: Variant` captured the alias *name* `"Variant"`, not its members, so on a TS-strict consumer (mayo) every HEAD came out with `variants: []` and ~25 with `props: {}`. Since the HEAD is the SSOT every UI agent reads for discovery, `variants: []` on a 6-variant Button induces wrong code. Separately, the variant axis was **hardcoded** to the prop name `variant` in three places — wrong for a `Chip`/`Pill` whose axis is `tone`. This release makes the extractor **optionally TS-aware** (it borrows the consumer's own `typescript`, resolved from the repo root) and adds a deterministic **`variant_prop`** field naming the real axis.

package/README.md

@@ -85,7 +85,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 - **agents/**: 26 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, component-manifest-schema, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
-### AI Agents (31 specialized agents)
+### AI Agents (32 specialized agents)
 
 **Core (required for every project)**
 1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
@@ -108,22 +108,23 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 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
-19. **ui-quality-critic** (v4.61.0): Stateless multimodal worker auto-invoked by `/e2e-review` Phase 4b — judges the **intrinsic design quality** of an implemented UI (10-dimension scientific rubric: hierarchy, rhythm, color, density, composition, states, motion, polish, brand) and returns a severity-tagged JSON report + per-dimension scores. The design twin of `code-reviewer`, the quality complement of `visual-fidelity-verifier` (needs no mockup). Never reads source, never grades its own design; fixes route to `ui-expert` in the bounded self-heal loop
+19. **markup-fidelity-verifier** (v4.78.0): Route-INDEPENDENT structural twin of `visual-fidelity-verifier`, auto-invoked by `/e2e-review` Phase 2.7 — compares the implementation's code structure against the mockup expressed as code (`links.design` HTML or `links.design_src`) with no browser/auth/data, catching the 2-column-mockup → 1-column-build class of divergence. READS code (mockup-vs-impl, no assertion-fitting risk); same canonical taxonomy + JSON output; fixes route to `ui-expert`
+20. **ui-quality-critic** (v4.61.0): Stateless multimodal worker auto-invoked by `/e2e-review` Phase 4b — judges the **intrinsic design quality** of an implemented UI (10-dimension scientific rubric: hierarchy, rhythm, color, density, composition, states, motion, polish, brand) and returns a severity-tagged JSON report + per-dimension scores. The design twin of `code-reviewer`, the quality complement of `visual-fidelity-verifier` (needs no mockup). Never reads source, never grades its own design; fixes route to `ui-expert` in the bounded self-heal loop
 
 **Product & Marketing**
-20. **onboarding-architect-lead**: User onboarding flow design and experimentation
-21. **marketing-conversion-strategist**: High-converting copy and messaging
-22. **seo-analytics-strategist**: SEO strategy, metadata, GA4/GTM event planning
-23. **email-deliverability-architect**: Transactional/informational email design + SPF/DKIM/DMARC
-24. **website-orchestrator**: Multi-agent website development coordination
+21. **onboarding-architect-lead**: User onboarding flow design and experimentation
+22. **marketing-conversion-strategist**: High-converting copy and messaging
+23. **seo-analytics-strategist**: SEO strategy, metadata, GA4/GTM event planning
+24. **email-deliverability-architect**: Transactional/informational email design + SPF/DKIM/DMARC
+25. **website-orchestrator**: Multi-agent website development coordination
 
 **Specialized**
-25. **hybrid-ml-architect**: ML/DL system design (recommenders, ranking, embeddings)
-26. **legal-counsel-gdpr**: GDPR compliance, privacy policies, data governance
-27. **deep-human-insight**: Psychological / sociological analysis for B2C UX and adoption
-28. **skill-improver**: Weekly auto-improvement of skills/agents based on review/QA findings
-29. **i18n-translator** (v4.52.0): Context-aware label translation into native locale files (Sonnet, low-effort, flag-not-guess) — invoked by `/i18n` + the `i18n-align` routine
-30. **merge-conflict-resolver** (v4.64.0): Resolves the final-merge **code** conflicts OFF the orchestrator context — auto-spawned by `/new` Phase 6 / `/mw` only when the deterministic `merge-worktree.sh` pauses on a code/test conflict. Adjudicates additive-vs-semantic hunks (semantic → STOP), then lets the script land. Runs in a fresh isolated context so the conflict churn never re-enters the bloated end-of-batch orchestrator
+26. **hybrid-ml-architect**: ML/DL system design (recommenders, ranking, embeddings)
+27. **legal-counsel-gdpr**: GDPR compliance, privacy policies, data governance
+28. **deep-human-insight**: Psychological / sociological analysis for B2C UX and adoption
+29. **skill-improver**: Weekly auto-improvement of skills/agents based on review/QA findings
+30. **i18n-translator** (v4.52.0): Context-aware label translation into native locale files (Sonnet, low-effort, flag-not-guess) — invoked by `/i18n` + the `i18n-align` routine
+31. **merge-conflict-resolver** (v4.64.0): Resolves the final-merge **code** conflicts OFF the orchestrator context — auto-spawned by `/new` Phase 6 / `/mw` only when the deterministic `merge-worktree.sh` pauses on a code/test conflict. Adjudicates additive-vs-semantic hunks (semantic → STOP), then lets the script land. Runs in a fresh isolated context so the conflict churn never re-enters the bloated end-of-batch orchestrator
 
 REGISTRY.md is the single source of truth for agent routing and capabilities.
 

package/VERSION

@@ -1 +1 @@
-4.77.0
+4.78.1

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

@@ -25,7 +25,8 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **hybrid-ml-architect** | ML | Design/implement ML systems end-to-end | Recommender, ranking, embeddings | Yes | Model design, evaluation, monitoring |
 | **i18n-translator** | Localization | Translate user-facing labels into the maintained target languages (invoked by `/i18n` + the `i18n-align` routine). Gated on `features.has_i18n`. | Context-aware translation using the per-key registry context, ICU/placeholder preservation, glossary adherence; bounded "flag-not-guess" self-healing (`needs-attention`) | Yes (writes native locale files ONLY — never app code, never the registry) | Native locale files, optional bulk backends (lingo.dev/languine) |
 | **ui-expert** | Design | Design, implement, 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 | Yes (generates UI / HTML mockups in `ui-design` Step C; a separate fresh instance acts as design-quality evaluator in Step D) | 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-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. Emits `data-state-mismatch` when the render is in the wrong data state. | Visual diff, severity taxonomy, design-system compliance check via registry cascade | No | Vision (multimodal), Read (screenshots + registry only), Playwright screenshots passed in by orchestrator |
+| **markup-fidelity-verifier** | Design | **Route-INDEPENDENT structural twin** of `visual-fidelity-verifier`: compare the implementation's code structure against the mockup expressed as code (`links.design` HTML or `links.design_src`/`mockups/_src/`) and return a severity-tagged JSON report — no browser, no auth, no data. Catches the 2-column-mockup → 1-column-build class of divergence (FEAT-0061). Auto-invoked by `/e2e-review` (Phase 2.7) — never spawned ad-hoc. Stateless. READS code (mockup-vs-impl, no assertion-fitting risk), never renders, never edits, never declares done. Same canonical severity taxonomy + JSON output as `visual-fidelity-verifier`. Fixes route to `ui-expert`. | Code-structural diff (DOM tree-edit-distance analogue), layout/grid/order/token-bypass, design-to-code fidelity | No | Read (mockup markup + implementation source) |
 | **ui-quality-critic** | Design | Judge the **intrinsic design quality** of an implemented UI screenshot against a scientific 10-dimension rubric (hierarchy, typographic & spacing rhythm, color/contrast, density, composition, states, motion, polish, brand) and return a severity-tagged JSON report + per-dimension scores. The design twin of `code-reviewer`; the fidelity complement of `visual-fidelity-verifier` (quality vs conformance — needs no mockup). Auto-invoked by `/e2e-review` (Phase 4b) — never spawned ad-hoc. Stateless, never reads source (anti assertion-fitting bias), never grades its own design, never edits, never declares done. Fixes route to `ui-expert`. Return Contract: JSON (already COMPACT). | Design-quality critique, rubric scoring, calibration anchors per dimension | No | Vision (multimodal), Read (screenshots + registry/guidelines only) |
 | **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 |

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

@@ -0,0 +1,239 @@
+---
+name: markup-fidelity-verifier
+description: "Compare an implemented UI's CODE STRUCTURE against its design mockup expressed as code (the HTML of `links.design`, or the finished-code of `links.design_src` / `mockups/_src/`) and return a severity-tagged JSON report. Route-INDEPENDENT structural twin of `visual-fidelity-verifier` — needs no browser, no auth, no live data. Reads both the mockup markup and the implementation source; reports layout/structure divergence (the 2-column-mockup → 1-column-build class of failure). Stateless worker invoked by the /e2e-review skill (Phase 2.7) — never edits code, never renders, never declares done."
+model: sonnet
+color: orange
+---
+
+You are the **Markup Fidelity Verifier**. You exist for one purpose: compare the
+**code structure** of an implemented UI against the **code structure of its design
+mockup** and return a deterministic, severity-tagged JSON report.
+
+You are the **route-independent, structural twin** of `visual-fidelity-verifier`.
+That agent compares *pixels* of a rendered screenshot against a mockup *image* — it
+needs a working render (browser, auth, data). You compare *markup/CSS structure*
+of the implementation source against the *markup structure of the mockup expressed
+as code* — you need **neither a browser nor a live render**. This is the analogue of
+**tree-edit-distance (TED) over the DOM** (the *structural* dimension of design-to-code
+evaluation), complementary to the visual verifier's SSIM/CLIP/LPIPS *perceptual*
+dimension. You catch the **2-column-mockup → 1-column-build** class of divergence
+that a pixel diff never sees because the page never rendered.
+
+You are stateless. You do not iterate. You do not fix. You do not render. You report
+what the implementation's code says structurally versus what the mockup's code says,
+with a severity tag and an actionable fix hint per finding. The orchestrating skill
+(`/e2e-review`) decides what to do with your output.
+
+**Scope vs the sibling verifiers.** You answer *"does the implementation's
+layout/structure match the mockup's layout/structure, as expressed in code?"* —
+**structural fidelity**. You do NOT judge pixel/perceptual match (`visual-fidelity-verifier`,
+which needs a render) and you do NOT judge whether the design is *good*
+(`ui-quality-critic`). Stay in your lane: structure derivable from code, cited at
+`file:line`.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:**
+`paths.design_system`, `paths.components_primitives`, `paths.components_root`,
+`paths.app_dir`, `paths.global_styles`,
+`features.has_design_system`, `features.e2e_review.fidelity_tolerance`.
+
+**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 `gaps[]` and downgrade
+gracefully (skip the check you lack inputs for). Do not assume defaults. See
+`framework/agents/project-context.md` § 3.
+
+## Hard Prohibitions (non-negotiable)
+
+- **NEVER edit any file.** You produce a JSON report only. The orchestrator delegates
+  fixes to `ui-expert` (layout/structure is UI domain) in a self-heal loop.
+- **NEVER render or screenshot.** You read code. If a divergence can only be confirmed
+  visually (color shade, anti-aliasing, sub-pixel offset), it is **out of your scope** —
+  leave it to `visual-fidelity-verifier`. Do not speculate about rendered appearance.
+- **NEVER propose architectural refactors.** Your scope is structural fidelity to the
+  mockup, 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.
+
+**Note on reading source.** Unlike `visual-fidelity-verifier` (which is forbidden from
+reading source to avoid assertion-fitting against a screenshot), reading code **is your
+job**: you compare *mockup code* (the ground-truth reference, not the app) against
+*implementation code*, structure to structure. There is no assertion-fitting risk — the
+mockup, not the implementation, is the oracle.
+
+## Input Contract
+
+The orchestrator (`/e2e-review`) invokes you with this JSON payload:
+
+```json
+{
+  "card_id": "FEAT-XXXX",
+  "route": "/settings",
+  "mockup_source": {
+    "level": "html" | "design_src",
+    "mockup_path": "/abs/path/to/mockup.html",         // level == html (links.design *.html)
+    "design_src_dir": "/abs/path/to/mockups/_src/"     // level == design_src (finished CODE, v4.75)
+  },
+  "implementation_files": [                              // the card's UI source (from the diff / File Ownership Map)
+    "/abs/path/<app_dir>/settings/settings-form.client.tsx",
+    "/abs/path/<app_dir>/settings/settings-form.module.css"
+  ],
+  "tolerance": "strict" | "balanced" | "lenient",
+  "resolved_orphans": [                                  // optional — Functional Traceability Gate
+    "Export CSV button", "bell icon"                     // mockup affordances deliberately dropped
+  ]
+}
+```
+
+- `mockup_source.level == "html"` — the mockup is a single HTML file (`links.design`).
+  Read it as the structural ground truth (its DOM nesting, its grid/flex declarations,
+  its element order, its region landmarks).
+- `mockup_source.level == "design_src"` — the mockup is finished Claude Design CODE
+  archived under `mockups/_src/` (JSX + CSS + tokens, v4.75). Read it the same way; it
+  speaks the project's own token language, so a near-1:1 structural mapping is expected.
+- `implementation_files` — the card's UI source. Read these and reconstruct the
+  implemented structure.
+
+If you cannot read a usable mockup (path missing/empty) **or** no implementation file
+contains layout-bearing markup/CSS, return
+`{ "status": "skipped", "reason": "no_structural_ground_truth", "findings": [] }`.
+
+**`resolved_orphans` carve-out (Functional Traceability Gate).** The mockup is a fidelity
+target, not a requirements oracle: an element matching an entry in `resolved_orphans`
+that is absent in the implementation is **EXPECTED — never a `component-missing`
+finding**. See `framework/agents/design-system-protocol.md` § "Functional Traceability
+Gate".
+
+## Severity Taxonomy (cite — do NOT redefine)
+
+The canonical severity taxonomy is SSOT in
+[`visual-fidelity-verifier.md`](visual-fidelity-verifier.md) § "Severity Taxonomy".
+Use it verbatim. You emit the subset that is **derivable from code structure** (never
+the perceptual ones):
+
+- **Critical:** `layout-break` (mockup declares a multi-column grid / side-by-side flex
+  row; implementation declares a single-column stack — **the canonical FEAT-0061
+  failure**), `element-order` (DOM/source order differs from the mockup), `component-missing`
+  (a designed region/block has no counterpart in the implementation), `component-duplicated`.
+- **Major:** `spacing-off-scale` (a literal where the mockup used a token/scale step,
+  detectable in code), `token-bypass` (hardcoded color/shadow/radius/spacing where the
+  mockup expressed a token — cross-checked against `tokens-reference.md` when
+  `has_design_system`), `responsiveness-break` (the mockup declares a breakpoint /
+  `@media` the implementation omits, leaving one viewport on the wrong layout).
+- **Do NOT emit** the purely perceptual categories (`color-mismatch`, `gradient-direction`,
+  `font-rendering-variance`, `shadow-off` by blur, `micro-misalignment`) — those require
+  a render and belong to `visual-fidelity-verifier`. If you suspect one, note it in
+  `gaps[]` for the orchestrator to route to the visual pass, do not emit it as a finding.
+
+`coverage-gap` and `data-state-mismatch` are **orchestrator/visual-verifier** concerns —
+never emitted by you.
+
+## Output Schema (STRICT — orchestrator parses programmatically)
+
+Identical to `visual-fidelity-verifier`'s schema so the orchestrator aggregates both
+uniformly:
+
+```json
+{
+  "status": "completed" | "skipped" | "error",
+  "route": "/settings",
+  "mockup_source_level": "html" | "design_src",
+  "findings": [
+    {
+      "severity": "critical" | "major" | "minor",
+      "category": "layout-break",
+      "description": "Mockup lays the form in a 2-column grid; implementation stacks it in a single column.",
+      "expected": "grid-template-columns: 1fr 1fr (mockup .form, settings-desktop.html:118)",
+      "actual": "flex-direction: column (settings-form.module.css:11)",
+      "fix_hint": "Change `.form` from `flex-direction: column` to a 2-column grid (`grid-template-columns: 1fr 1fr` with the project's column gap token), matching the mockup's two-section layout. File: settings-form.module.css:11.",
+      "evidence": {
+        "mockup_ref": "mockups/settings-desktop.html:118",
+        "impl_ref": "<app_dir>/settings/settings-form.module.css:11"
+      },
+      "ds_drift_code": "DS_TOKENS_DRIFT" | null,
+      "confidence": "high" | "medium" | "low"
+    }
+  ],
+  "ds_drift_codes": [],
+  "gaps": [
+    "color/shade divergence suspected at the header — needs the visual pass (out of structural scope)"
+  ],
+  "transcript_path": "/tmp/e2e-review/FEAT-XXXX/markup-fidelity-transcript.md"
+}
+```
+
+**Field rules** (mirror `visual-fidelity-verifier`):
+- `expected` / `actual` cite the **structural declaration** on each side with `file:line`
+  (e.g. the CSS property + value, the JSX nesting, the `@media` query) — never a vague
+  description when a concrete line exists.
+- `fix_hint` MUST be actionable and name the file + property to change. If you cannot
+  produce an actionable hint, drop the finding's severity by one tier (or remove it if
+  Minor). Route in your wording to a CSS/markup change (the orchestrator sends it to
+  `ui-expert`).
+- `confidence`: `high` when both sides are unambiguous in code; `medium` when the
+  implementation's structure is computed/dynamic (e.g. classes assembled at runtime) and
+  you inferred it; `low` when you are guessing — prefer dropping a low-confidence finding.
+- `ds_drift_code` set to `DS_TOKENS_DRIFT` only for `token-bypass` findings.
+
+## Comparison Protocol
+
+1. **Read the mockup code** (HTML or `design_src`). Reconstruct its structure: top-level
+   regions and their order; for each region, the layout primitive (grid vs flex, column
+   count, `gap`), the element order within it, and any `@media`/breakpoint behavior.
+2. **Read the implementation files**. Reconstruct the same structure from the JSX tree +
+   the CSS/CSS-modules/Tailwind classes. Resolve Tailwind utilities (`grid-cols-2`,
+   `flex-col`, `md:grid-cols-2`) and CSS-module rules to their layout meaning.
+3. **Compare structure first** (the cheap, high-value Critical findings): does the
+   implementation reproduce the mockup's column count / grid-vs-stack / side-by-side
+   rows? Is the region order the same? Is every designed region present?
+4. **Then compare responsive structure**: does the implementation carry the mockup's
+   breakpoints (`@media`, `md:`/`lg:` prefixes)? A mockup desktop-2-col / mobile-1-col
+   that the implementation renders 1-col at ALL widths is a `responsiveness-break` (or
+   `layout-break` at the designed width).
+5. **Then check token-bypass** (when `has_design_system`): hardcoded values in the
+   implementation where the mockup used a token / the registry has one — cross-check
+   `${paths.design_system}/tokens-reference.md`.
+6. **Compose findings** into the JSON schema. Order by severity (Critical → Major),
+   then category. Cite `file:line` on both sides.
+
+## Anti-Hallucination Discipline
+
+- Flag only what is **evidenced in BOTH** the mockup code and the implementation code,
+  with a `file:line` on each side. If you cannot point to the mockup declaration and the
+  implementation declaration, do not emit the finding.
+- When the implementation's structure is assembled dynamically (conditional classes,
+  composed children you cannot statically resolve), say so in `gaps[]` and lower
+  confidence — do not invent a divergence.
+- Anything that needs a render to confirm (exact color, shadow softness, sub-pixel
+  alignment) is **out of scope** — note it in `gaps[]` for the visual pass, never emit it.
+- Cite tokens by **exact name** as they appear in `tokens-reference.md`.
+
+## What You Are Not
+
+- You are not `visual-fidelity-verifier`. It compares a rendered screenshot to a mockup
+  image (pixels). You compare code structure to code structure (markup). You run when the
+  route may not even render.
+- You are not `ui-quality-critic`. That agent judges intrinsic design quality. You only
+  compare structure to the mockup.
+- You are not `code-reviewer`. That agent reviews source for bugs/quality across the whole
+  diff. You only check structural fidelity to the design mockup.
+- You are not the orchestrator. `/e2e-review` aggregates your findings, runs the self-heal
+  loop (routing your findings to `ui-expert`), and produces the pass/block decision.
+
+## Linked Protocols
+
+- [`framework/agents/visual-fidelity-verifier.md`](visual-fidelity-verifier.md) — SSOT for
+  the severity taxonomy you cite, and your perceptual sibling.
+- [`framework/agents/design-system-protocol.md`](../../agents/design-system-protocol.md) —
+  § "Structural Fidelity (route-free)", § "Functional Traceability Gate", token cascade,
+  drift codes.
+- [`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.

package/framework/.claude/agents/prd-card-writer.md

@@ -250,7 +250,12 @@ since v4.18.0 a per-card Codex finder + `code-reviewer` FP-gate — plus `code-r
 the registry-first DS cascade, and is covered by the batch-wide Final FULL gate). Any
 doubt — a hint of logic, state, data binding, a new/modified primitive, or `areas` beyond
 `[ui]` — disqualifies branch (b): the card stays `balanced`. When in doubt between `balanced`
-and `deep`, choose `deep`. `files_likely_touched` counts are advisory only — never downgrade a
+and `deep`, choose `deep`. **Pure-graphics fast-lane (since v4.78.0):** a branch-(b) card MUST
+also carry `owner_agent: ui-expert` (per Rule B — `ui-expert` is the builder of pure-UI
+surfaces). The triple `owner_agent: ui-expert` + `review_profile: light` + `areas == [ui]` is
+the canonical **pure-graphics card** that `/new` recognizes to skip Simplify + per-card Codex
+(the `/e2e-review` fidelity trio is its review) — so always emit `owner_agent: ui-expert`
+explicitly on a branch-(b) card, never leave it implicit. `files_likely_touched` counts are advisory only — never downgrade a
 **logic-bearing** card below `balanced` because the file count looks small. **Epic cards**
 always use `review_profile: skip` (no code work).
 

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

@@ -108,6 +108,26 @@ inert) in the rendered output is **EXPECTED — never a `component-missing` or
 raw mockup. See `framework/agents/design-system-protocol.md` § "Functional
 Traceability Gate".
 
+## Data-State Awareness (never compare a degenerate render)
+
+Before diffing, judge whether the render is in a **comparable data state**. The mockup
+depicts a *specific, usually populated* state (a table with rows, a list of products, a
+selected store/tenant). If the render shows an **empty-state, loading placeholder, "no
+data" message, an error page, or an obviously wrong context** (e.g. a different
+tenant/store than the one the mockup depicts), the screenshot is **not comparable** —
+emit a single `data-state-mismatch` (Critical) finding describing the gap and STOP
+(return that one finding; do not also emit layout/typography findings derived from an
+empty screen). Do **not** report "matches" just because both look sparse. The
+orchestrator (`/e2e-review`) owns reaching the depicted state (seed data / select a
+populated context) and will re-invoke you on the corrected render — your job is only to
+flag that the state is wrong, never to navigate or seed.
+
+A skip is legitimate ONLY when `mockup_source.level == "skip"` (genuinely no mockup). An
+empty/degenerate render of a route that HAS a mockup is a `data-state-mismatch`, never a
+silent skip or a pass. (A mockup provided as an HTML file rendered to PNG by the
+orchestrator arrives to you as `mockup_source.level == "local"` — treat it as any other
+local image ground truth.)
+
 ## Severity Taxonomy (CANONICAL — cite verbatim)
 
 This taxonomy is the SSOT consumed by `/e2e-review` and `/design-review`. Do
@@ -123,6 +143,8 @@ not invent new severity levels. Do not move categories across tiers.
 | `component-missing` | Designed component absent from rendered output (e.g. mockup has a CTA card, screen does not). **Exception:** an element listed in `resolved_orphans` is expected-absent — do NOT flag it. |
 | `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 |
+| `data-state-mismatch` | The render is in the **wrong DATA STATE** to compare against the mockup: the mockup depicts a populated screen (table with rows, list of cards, a selected entity) but the render shows an **empty-state / placeholder / "no data" / wrong-context** screen. You CAN emit this (you see the emptiness). It tells the orchestrator the screenshot is not comparable and must be re-rendered in the depicted state (seed / select a populated context) — **not** that the implementation is wrong. Never silently "match" an empty render against a populated mockup. |
+| `coverage-gap` | **Orchestrator-emitted, NOT by you.** A mockup existed for the route but the fidelity check could not be executed at all (route unrenderable in every lane, no isolated render available). Listed here because this taxonomy is the SSOT the `/e2e-review` gate consumes; the orchestrator synthesizes it so an un-runnable required check **blocks** instead of silently passing. |
 
 ### Major (BLOCKS in strict + balanced; advisory in lenient)
 

package/framework/.claude/skills/ds-edit/SKILL.md

@@ -144,6 +144,13 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
 8. **Coherence report (never silent).** Emit the protocol's "Registry coherence
    check: N findings" block: spec updated (incl. HEAD), INDEX/policy reconciled,
    tokens reconciled, breaking change documented + migration noted.
+   **Mirror (advisory, non-blocking):** modifying a canonical component or token
+   moves the registry ahead of its Claude Design satellite — so when a satellite is
+   bound (`.baldart/design-sync.json` has a `project_id`), also surface
+   `DS_MIRROR_STALE` (check #6, `design-system-protocol.md` — cite, do not redefine)
+   nudging `/design-sync publish`. For a **breaking** edit the satellite drift is
+   the same class as the migration — note both. Skipped when no satellite is bound;
+   never blocks the edit.
 
 ## Token edit path
 
@@ -183,3 +190,5 @@ symmetric to how a `NEW (governed)` standard routes to `/ds-new`. `/prd` owns th
 - `framework/agents/component-manifest-schema.md` — the HEAD schema + the
   regeneration contract (preserve agentic, regenerate deterministic).
 - `framework/templates/breaking-change-checklist.md` — for breaking edits.
+- `framework/.claude/skills/design-sync/SKILL.md` — `/design-sync publish` mirrors
+  the edit UP to the Claude Design satellite (the `DS_MIRROR_STALE` nudge).

package/framework/.claude/skills/ds-new/SKILL.md

@@ -139,6 +139,12 @@ Each step is a delegation. Read the cited SSOT; do not paraphrase it.
 8. **Coherence report (never silent).** Emit the protocol's "Registry coherence
    check: N findings" block (per § Post-Intervention Coherence Check): new spec
    shipped, INDEX entry added, tokens reconciled, closed-set respected.
+   **Mirror (advisory, non-blocking):** creating a canonical component or token is
+   exactly the event that moves the registry ahead of its Claude Design satellite —
+   so when a satellite is bound (`.baldart/design-sync.json` has a `project_id`),
+   also surface `DS_MIRROR_STALE` (check #6, `design-system-protocol.md` — cite, do
+   not redefine) nudging `/design-sync publish`. Skipped when no satellite is bound;
+   never blocks creation.
 
 ---
 
@@ -196,4 +202,6 @@ across the two.
   the serializer fills (the standardized doc shape).
 - `framework/.claude/skills/design-system-init/SKILL.md` — the bulk twin; shares
   the same scripts (`extract-manifest`/`extract-one`/`serialize-spec`).
+- `framework/.claude/skills/design-sync/SKILL.md` — `/design-sync publish` mirrors
+  the new element UP to the Claude Design satellite (the `DS_MIRROR_STALE` nudge).
 - `framework/docs/COMPONENT-MANIFEST-LAYER.md` — the layer overview.

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -208,16 +208,31 @@ available (probe `get_design_context` / `get_screenshot` tools at runtime):
 If the MCP tools error or time out, fall through silently to level (b) — do
 not surface the failure as a blocker.
 
-### Level (b) — Local image
-
-If `card.links.design[]` contains a local file path (PNG / JPG / PDF) OR the
-card has a `mockups/` directory alongside its YAML:
-
-- Resolve the path. For PDFs, extract the first page as PNG (use `pdftoppm`
-  or equivalent — degrade gracefully if unavailable).
-- Copy to `.baldart/e2e-review/<CARD-ID>/mockups/<route-slug>.local.png`.
+### Level (b) — Local image (PNG / JPG / PDF / **HTML**)
+
+If `card.links.design[]` contains a local file path OR the card has a `mockups/`
+directory alongside its YAML:
+
+- **PNG / JPG**: copy to `.baldart/e2e-review/<CARD-ID>/mockups/<route-slug>.local.png`.
+- **PDF**: extract the first page as PNG (`pdftoppm` or equivalent — degrade gracefully
+  if unavailable).
+- **HTML** (`links.design` ends in `.html`): the mockup is markup, not an image. Two
+  things happen — (1) render it headless to a PNG for the visual pass: open `file://<abs
+  path>` with Playwright at 1440px and `page.screenshot({fullPage:true})` →
+  `.baldart/e2e-review/<CARD-ID>/mockups/<route-slug>.local.png` (degrade gracefully if
+  the render fails — the structural pass below still runs); (2) **retain the HTML path**
+  for the route-free structural pass (Phase 2.7).
 - Record `mockup_source.level = "local"` and the source path.
 
+**Structural source (route-free ground truth).** Independently of the image, record a
+`structural_source` for the route when the mockup is **code**:
+- `links.design` is an `.html` file → `structural_source = { level: "html", mockup_path:
+  "<abs html path>" }`.
+- `links.design_src` is set / `mockups/_src/` exists (finished Claude Design CODE, v4.75)
+  → `structural_source = { level: "design_src", design_src_dir: "<abs dir>" }`.
+This feeds Phase 2.7 (`markup-fidelity-verifier`) and is what makes per-card fidelity
+verifiable **without rendering the live route**.
+
 ### Level (c) — Compliance-only (registry)
 
 If no mockup image is available BUT `features.has_design_system: true`:
@@ -244,6 +259,59 @@ The cascade output is appended to the plan under `mockup_refs[]`.
 
 ---
 
+## Phase 2.7 — Structural Fidelity (route-free, runs BEFORE the browser)
+
+**Goal**: catch layout/structure divergence from the mockup **without rendering the live
+route** — the route-independent first line of defense. This is what would have caught
+FEAT-0061 (a 2-column desktop mockup built as a single column) even though the
+auth-gated route returned 500 in the harness. SSOT: `framework/agents/design-system-protocol.md` §
+"Route-Independent Fidelity & Coverage Obligation" → 1. Structural Fidelity.
+
+**When it runs**: for every route whose `structural_source` was recorded in Phase 2
+(`level == "html"` or `"design_src"`). Skip the route here only when there is no
+code-form mockup (image-only `figma`/PNG mockups have nothing to diff structurally —
+they go through Phase 4 visual + the coverage obligation instead).
+
+For each such route:
+
+1. **Resolve the implementation files** for the route from the diff / the card's File
+   Ownership Map (the `*.tsx` / `*.css` / `*.module.css` / `*.scss` / `*.svelte` / `*.vue`
+   the card touched under `${paths.app_dir}` / `${paths.components_root}`).
+2. **Invoke `markup-fidelity-verifier`** (input contract in
+   [`markup-fidelity-verifier.md`](../../agents/markup-fidelity-verifier.md)):
+
+   ```
+   subagent_type: "markup-fidelity-verifier"
+   mode: "bypassPermissions"   // when called from /new
+   prompt: |
+     Compare the implementation's code structure against the mockup's code structure
+     and return JSON per your output schema.
+
+     Input payload:
+     {
+       "card_id": "FEAT-XXXX",
+       "route": "/settings",
+       "mockup_source": { ...the route's structural_source (html | design_src)... },
+       "implementation_files": [ ...abs paths the card touched for this route... ],
+       "tolerance": "<from config>",
+       "resolved_orphans": [ ...from the card's UI Element Inventory, as in Phase 4... ]
+     }
+   ```
+3. **Parse the JSON strictly** (same discipline as Phase 4). On malformed output log
+   `markup_verifier_protocol_violation` in `gaps[]` and treat the route's structural
+   findings as empty.
+4. **Aggregate** structural findings into `structural_findings[]` (tag each `source:
+   "structural"`). They flow into the Phase 5 gate under the canonical taxonomy — a
+   `layout-break` here is Critical and BLOCKS. Because this runs before Phase 3/4, a clear
+   structural divergence blocks **cheaply**, before the expensive browser + multimodal
+   passes.
+
+This phase is **route-independent**: it never starts a dev server, never authenticates,
+never needs data. It is the workhorse of per-card fidelity; the render passes (Phase 4)
+are the confirmation.
+
+---
+
 ## Phase 3 — Functional E2E (browser-based)
 
 **Goal**: execute the Gherkin scenarios from Phase 1 in a real browser and
@@ -324,11 +392,72 @@ capture the result + screenshots per route.
    - `failure_reason` (when failed, the first assertion error + stack hint)
    - `screenshot_paths[]` (per route: the desktop `<route-slug>.png` AND the
      mobile `<route-slug>@mobile.png`)
+   - `render_health` (per route): the HTTP status of the route navigation and
+     whether the screenshot is a **degenerate render** — a non-2xx/error page, or
+     a blank/empty-state page. Capture the response status from the Playwright
+     navigation (`response.status()`); flag `degenerate: true` when status is not
+     2xx OR the page has no meaningful content. This drives Phase 3.8.
 5. **Functional findings**: every `failed` or `flaky` scenario becomes a
    functional finding in the aggregate report (Phase 5). Severity:
    - Auth / payments / data-mutation scenario failed → `critical`
    - Display-only scenario failed → `major`
    - Flaky (passed on retry) → `minor` with `confidence: low`
+   - **A `skipped` scenario is NOT silently dropped when its route has a mockup
+     (`mockup_source.level != "skip"`)**: a skip means the fidelity check did not
+     run, which is a coverage concern, not a pass — it is carried into Phase 3.8
+     (state remediation) and, if still un-renderable, into the coverage obligation
+     (Phase 4 step 1c). Silently skipping a mockup'd route is the exact FEAT-0061
+     failure and is prohibited.
+
+---
+
+## Phase 3.8 — Comparable-render gate (route-independent lane + state remediation)
+
+**Goal**: guarantee that the screenshot handed to Phase 4 is **comparable to the
+mockup** — rendered route-independently where possible, and in the **data state the
+mockup depicts**. The reviewer never accepts "I opened the page, it's empty, I skip".
+SSOT: `design-system-protocol.md` § "Route-Independent Fidelity & Coverage Obligation"
+→ 2. Visual Fidelity + 3. State-aware Fidelity.
+
+For each route with a mockup (`mockup_source.level != "skip"`):
+
+1. **Pick the render lane** (priority order):
+   - **(a) Isolated render** — when the route's primary surface is a **registry
+     primitive** (a component documented under `${paths.components_primitives}` with a
+     spec HEAD), render it in isolation via the `/ds-render` harness (`baldart render
+     build|shot`). This needs no route, no auth, no data — the route-independent visual
+     confirmation. Save to `.baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>.iso.png`
+     and use it as the implementation screenshot for Phase 4. (Composed page surfaces are
+     NOT auto-rendered in isolation — that was refuted in v4.76; they use lane (b).)
+   - **(b) Live-route screenshot** from Phase 3, when the route rendered cleanly
+     (`render_health.degenerate != true`).
+2. **State remediation (the reach-state loop)** — when the chosen render is **degenerate**
+   (`render_health.degenerate == true`: non-2xx, empty-state, wrong tenant/store) and the
+   mockup depicts a populated state, do NOT accept it. Run a **bounded** loop (cap = 2):
+   - Read the consumer's `.baldart/overlays/e2e-review.md` **reach-state recipes** and run
+     the applicable ones in order: `seed_data` → `select_populated_context` (the multi-store
+     case: select a store/tenant that has data) → `goto_populated_entity`. Re-render, re-check
+     `render_health`.
+   - **Generic fallbacks when no recipe exists**: authenticate with the persona's real
+     creds (`test_plan.test_credentials`); enable MSW/API-mock of the data response if the
+     project supports it; apply a deterministic factory/snapshot seed; or heuristically
+     auto-seek a populated context via `webapp-testing` (enumerate an on-screen
+     store/tenant selector, pick the option that yields non-empty content).
+   - Stop as soon as a non-degenerate, populated render is produced.
+3. **Outcome**:
+   - A comparable render was produced → it is the implementation screenshot for Phase 4.
+   - Still degenerate after the loop **and** the mockup is **code-form** (a Phase 2.7
+     `structural_source` exists) → the structural pass already covered fidelity; record
+     `render_unavailable` in `gaps[]` and let Phase 4's visual step skip this route's
+     desktop diff (no false coverage-gap — structure was checked route-free).
+   - Still degenerate after the loop **and** the mockup is **image-only**
+     (`level ∈ {figma, local}` with no `structural_source`) → mark the route
+     `coverage_obligation_unmet = true` for Phase 4 step 1c (it will synthesize a
+     `coverage-gap`).
+
+The orchestrator owns navigation/seeding here; `visual-fidelity-verifier` stays stateless
+and only judges the frame it is handed (emitting `data-state-mismatch` if the state is
+still wrong).
 
 ---
 
@@ -353,8 +482,19 @@ For each `route` in `plan.routes[]`:
    - When `mockup_source.level == "skip"`, skip the **desktop fidelity diff**
      (steps 2) for this route — but still run the **mobile responsive pass**
      (step 2b) if a `<route-slug>@mobile.png` screenshot was captured, since it
-     needs no mockup. Skip the route entirely only when no screenshot exists
-     (route unrenderable).
+     needs no mockup.
+   - **1c. Coverage obligation (un-runnable required check BLOCKS, never passes).**
+     When the route is marked `coverage_obligation_unmet = true` from Phase 3.8 (an
+     **image-only** mockup — `level ∈ {figma, local}` with no `structural_source` — that
+     could not be rendered in any lane and whose state could not be reached), **synthesize
+     a `coverage-gap` finding (Critical)** instead of silently skipping the route. SSOT:
+     `design-system-protocol.md` § "...→ 4. Coverage Obligation". **Guards — NEVER synthesize
+     `coverage-gap`** when `mockup_source.level` is `skip` / `harness-render` /
+     `compliance-only`, nor for the mobile pass (it runs at `level: skip`), nor when a
+     Phase 2.7 `structural_source` already covered fidelity route-free. A `coverage-gap`
+     is **not fixable by an agent** — it bypasses the Phase 5b self-heal loop and maps to
+     the `blocked` verdict (the route still will not render). This is the guard that turns
+     the FEAT-0061 "skip masked as pass" into a real block.
    - When `mockup_source.level == "harness-render"` (a render-harness PNG of an
      ISOLATED registry primitive, from `/ds-render` — Stage C of the closed loop),
      **NEVER run the fidelity diff (step 2)**: the image is a render of the
@@ -505,14 +645,20 @@ For each such `route`:
 the canonical severity taxonomy from `visual-fidelity-verifier.md`.
 
 1. **Compose** the `findings[]` array:
+   - **Structural findings** from Phase 2.7 (`source: "structural"`) — route-free
+     code-structure divergence (`markup-fidelity-verifier`).
    - Functional findings from Phase 3 (`source: "functional"`).
-   - Visual findings from Phase 4 (`source: "visual"`).
+   - Visual findings from Phase 4 (`source: "visual"`) — including any
+     `data-state-mismatch` (the verifier saw an empty/wrong-state render) and any
+     orchestrator-synthesized `coverage-gap` (Phase 4 step 1c — a required check that
+     could not run at all).
    - Design-quality findings from Phase 4b (`source: "design-quality"`).
    - Each finding carries: `severity`, `category` (or `dimension` for
      design-quality), `source`, `route`, `description`, `expected`, `actual`,
-     `fix_hint`, `evidence`, `ds_drift_code`, `confidence`. All three sources
+     `fix_hint`, `evidence`, `ds_drift_code`, `confidence`. All sources
      share the **same canonical severity taxonomy**, so the tolerance filter in
-     step 2 applies to them uniformly — no per-source special-casing.
+     step 2 applies to them uniformly — no per-source special-casing. (`coverage-gap`
+     and `data-state-mismatch` are Critical and gate in every tolerance.)
 2. **Apply tolerance filter** based on
    `features.e2e_review.fidelity_tolerance`:
    - `strict` (DEFAULT): Critical + Major + Minor all gate. Additionally,
@@ -533,16 +679,25 @@ applies only when `verdict == "blocked"` AND `iteration < max`.
 
 For each iteration:
 
-1. **Route the gating findings to the right fixer by `source`**, then spawn the
-   fixer(s). Design-quality fixes are UI-scoped (presentation / layout / styling
-   / motion) — they belong to `ui-expert`, the UI domain owner, NOT to `coder`.
-   Functional fixes belong to `coder`. (Visual-fidelity findings follow their
-   nature: token/spacing/typography fixes route to `ui-expert`; a missing or
-   mis-wired element route to `coder`.) When both buckets are non-empty, run
-   `coder` first (structure), then `ui-expert` (presentation), so the critic
-   re-evaluates the final surface.
-
-   - **`ui-expert`** — gating findings where `source == "design-quality"` (and
+0. **`coverage-gap` findings bypass the loop.** A `coverage-gap` is not fixable by any
+   agent (the route still will not render — it is a harness/data limitation, not a code
+   defect). Do NOT spawn a fixer for it. It keeps the verdict `blocked` and flows straight
+   to the override path below (programmatic mode returns `blocked`; `/new` escalates it to
+   a follow-up card). If `coverage-gap` is the ONLY gating finding, skip the rest of this
+   loop entirely.
+
+1. **Route the remaining gating findings to the right fixer by `source`**, then spawn the
+   fixer(s). **Fidelity is UI-scoped**: `source == "structural"` (layout/grid/order —
+   `markup-fidelity-verifier`), `source == "design-quality"`, and UI-presentation
+   `source == "visual"` (token/spacing/typography/color, `data-state-mismatch` left to
+   state remediation) all belong to **`ui-expert`**, the UI domain owner, NOT `coder`.
+   `coder` gets only `source == "functional"` and genuine **wiring/data-binding** visual
+   findings (a missing element that is unwired, not mis-laid-out). When both buckets are
+   non-empty, run `coder` first (structure/wiring), then `ui-expert` (presentation), so the
+   critic re-evaluates the final surface. **On a pure-graphics card (`owner_agent:
+   ui-expert`), ALL fidelity fixes go to `ui-expert` — `coder` is not involved.**
+
+   - **`ui-expert`** — gating findings where `source in {structural, design-quality}` (and
      UI-presentation `source == "visual"` findings):
 
      ```
@@ -553,13 +708,16 @@ For each iteration:
 
      ## Gating findings
      [paste the JSON findings filtered to gating severity, source in
-      {design-quality, visual}]
+      {structural, design-quality, visual}]
 
      ## Rules
      - File ownership: stay within the card's allowed file set (see
        /tmp/batch-tracker-<FIRST-CARD-ID>.md ## File Ownership Map).
      - One fix per finding. Reuse existing tokens / primitives before inventing
        new ones (cite ${paths.design_system}/INDEX.md + tokens-reference.md).
+     - For a `structural` `layout-break`, match the mockup's layout exactly (e.g.
+       restore the 2-column grid the mockup declares) — cite the mockup ref in the
+       finding's `expected`.
      - Run the Post-Intervention Coherence Check on any registry-touching fix.
      - After the fixes, re-run lint and typecheck. Both must pass.
      - Do NOT modify Playwright specs or this skill's state files.
@@ -594,8 +752,10 @@ For each iteration:
 
    Both fixers run in `bypassPermissions` mode when called by `/new`.
 
-2. **Re-run Phase 3 (functional), Phase 4 (visual), and Phase 4b (quality)**
-   with fresh screenshots. Increment `iteration`.
+2. **Re-run the affected verifiers**: Phase 2.7 (structural, route-free — re-run when a
+   `structural` fix was applied), Phase 3 (functional), Phase 3.8 (re-render / state),
+   Phase 4 (visual), and Phase 4b (quality) with fresh screenshots. Increment `iteration`.
+   (A `coverage-gap`-only block does not enter this loop — see step 0.)
 3. **Re-aggregate and re-decide** (back to Phase 5 step 1).
 4. **STOP** when `verdict == "passed"` OR `iteration == max`.
 
@@ -698,8 +858,14 @@ and starts from Phase 3 (skipping plan extraction and mockup cascade).
 - **`/design-review` command** — when invoked from this skill with
   `mode: "programmatic"`, returns JSON instead of Markdown for gating.
   See [`framework/.claude/commands/design-review.md`](../../commands/design-review.md).
+- **`markup-fidelity-verifier`** (Phase 2.7) — route-free structural twin of
+  `visual-fidelity-verifier`: compares the mockup's code structure (HTML / `design_src`)
+  against the implementation source, no render. See
+  [`markup-fidelity-verifier.md`](../../agents/markup-fidelity-verifier.md). Its fixes
+  route to `ui-expert`.
 - **`visual-fidelity-verifier`** (Phase 4) — judges fidelity to the mockup /
-  spec. See [`visual-fidelity-verifier.md`](../../agents/visual-fidelity-verifier.md).
+  spec (pixels), and emits `data-state-mismatch` when the render is in the wrong data
+  state. See [`visual-fidelity-verifier.md`](../../agents/visual-fidelity-verifier.md).
 - **`ui-quality-critic`** (Phase 4b) — judges intrinsic design quality against
   the rubric, independent of any mockup. See
   [`ui-quality-critic.md`](../../agents/ui-quality-critic.md). It is the design
@@ -740,6 +906,9 @@ and starts from Phase 3 (skipping plan extraction and mockup cascade).
 | Quality loop never converges (design-quality findings persist) | Taste-leaning Minor findings, or `ui-expert` fixing one dimension while regressing another | Confirm the findings are gating (not low-confidence Minor auto-demoted in strict). If genuine and unresolved after max iterations, override with reason and open a `ui-expert` follow-up card — do NOT block indefinitely on subjective polish |
 | `quality_critic_protocol_violation` in gaps | `ui-quality-critic` returned prose mixed with JSON | Re-spawn the critic once; if persistent, surface to user (likely a model regression). Treat that route's quality findings as empty meanwhile |
 | `verifier_protocol_violation` in gaps | `visual-fidelity-verifier` returned prose mixed with JSON | Re-spawn the verifier once; if persistent, surface to user (likely a model regression) |
+| `coverage-gap` (Critical) on a route | An image-only mockup route could not be rendered in any lane and its state could not be reached | Correct by design — the gate BLOCKS instead of silently passing. Add a reach-state recipe to `.baldart/overlays/e2e-review.md` (seed / select populated context), or provide an HTML/`design_src` mockup so the route-free structural pass covers it. Never override without fixing the lane |
+| `data-state-mismatch` (Critical) on a route | Render opened an empty / wrong-tenant / error state; mockup depicts a populated state | The reach-state loop (Phase 3.8) should seed/select a populated context. If it has no recipe and cannot auto-seek, add `select_populated_context` / `seed_data` to the e2e-review overlay |
+| `markup_verifier_protocol_violation` in gaps | `markup-fidelity-verifier` returned prose mixed with JSON | Re-spawn once; if persistent, surface to user. Treat that route's structural findings as empty meanwhile |
 
 ---
 

package/framework/.claude/skills/new/references/codex-gate.md

@@ -44,7 +44,21 @@ Log the detector output in the tracker for traceability. **This step never short
 > `baldart teardown-codex-broker`), with the `baldart doctor` reaper as the safety net. Per-card hygiene
 > is none.
 
-For EVERY card (no conditional skip — the gate ALWAYS runs; only its DEPTH varies):
+**Pure-graphics-card skip (narrow exception — since v4.78.0).** Skip the per-card
+`/codexreview` gate entirely when the card is **pure-graphics**: `owner_agent: ui-expert`
+**AND** `review_profile: light` **AND** `areas == [ui]` exactly (no `api`/`data`/`logic`/`auth`
+area) **AND** Step A matched **zero** high-risk triggers on the actual diff. Rationale: a
+zero-logic UI card's meaningful review is the **`/e2e-review` fidelity trio** —
+`markup-fidelity-verifier` (structure) + `visual-fidelity-verifier` (pixels + a11y) +
+`ui-quality-critic` (quality) — plus the mechanical build/lint/tsc gates; a general Codex
+bug-sweep over presentational CSS/JSX is low-value noise (the user's "qa codex review non
+serve" for graphics). **Safety net preserved:** the **Final-review FULL `/codexreview`**
+(net #2 below) ALWAYS re-sweeps the ENTIRE batch diff before merge — so the graphics card's
+code is still Codex-reviewed batch-wide, just not per-card. The Step-A zero-trigger condition
+means any high-risk path on the diff cancels the skip (escalation-only invariant). Log
+`codex: SKIPPED (pure-graphics — fidelity trio is the review; Final FULL gate re-sweeps)`.
+
+For EVERY other card (no conditional skip — the gate ALWAYS runs; only its DEPTH varies):
 
 0. **Select the Codex review profile (deterministic — Review Profile Selector)** by mapping the
    card's review profile (read from the card's `review_profile` field per the QA Profile Selector

package/framework/.claude/skills/new/references/completeness.md

@@ -263,6 +263,8 @@ This gate enforces `framework/agents/workflows.md § Scope Closure Discipline` a
 
    Do NOT batch the question across multiple ACs — one `AskUserQuestion` per AC, so the user sees each AC's text in isolation. Issue the questions sequentially.
 
+   **Fidelity-AC carve-out (BLOCKING — the FEAT-0061 fix).** When the deferred AC is a **visual-fidelity AC** — its text matches `/visual|fidelit|mockup|layout|responsive|1:1|design (match|reference)/i` OR it asserts the screen matches a design reference (`links.design` / `links.design_src`) — option 2 **"Approva il deferral" is NOT offered**. A fidelity AC cannot be silently deferred or "covered by a downstream card": that is exactly the `FEAT-0061-08 → 04/10` cross-card deferral that shipped a 1-column page against a 2-column mockup. Offer only **1 (Implementa adesso — route the fix to `ui-expert`)**, **3 (Sposta su follow-up card — explicit, tracked, and the new card carries the fidelity AC + `links.design`, so it re-faces the `/e2e-review` gate)**, **4 (Ferma il batch)**. **When AUTONOMOUS:** take option 3 (follow-up card) — never approve the deferral. Note: with the route-free structural pass (`/e2e-review` Phase 2.7) a UI card now verifies its OWN surface without a live route, so a genuine *need* to defer fidelity should be rare; treat a fidelity deferral as a signal that the per-card gate was skipped, not as a routine outcome.
+
 5. **`implementation_notes` deferral audit (cheap text grep — also BLOCKING)** — before exiting the phase, scan the card YAML's `implementation_notes` field (post-edits, including any text added during this phase) for any of these phrases:
 
    - `deferred` / `deferral` / `defer to`

package/framework/.claude/skills/new/references/review-cycle.md

@@ -116,6 +116,8 @@ so it surfaces in telemetry.
 
 > **Trivial fast-lane gate**: re-confirm `IS_TRIVIAL` on the ACTUAL committed diff (§ "Trivial-card fast-lane" — all 3 conditions, now including the real non-source diff check). If trivial → **SKIP this phase** AND Phase 3.5 QA + Phase 3.7 Codex; instead run the **inline mechanical gates** (`markdownlint` on changed `.md`, `lint` on lintable changed files, `build` as a sanity check — no qa-sentinel, no test suite), then proceed to Phase 3 (doc review, which DOES run) and Phase 4 (commit). Log `simplify/qa/codex: SKIPPED (trivial — non-source diff)`. If the actual diff turned out to contain a source file → NOT trivial → run this phase and the normal review path. AC-Closure (Phase 2.5b) already ran and is never skipped.
 
+> **Pure-graphics fast-lane gate (since v4.78.0)**: when the card is **pure-graphics** (`owner_agent: ui-expert` AND `review_profile: light` AND `areas == [ui]` exactly — no api/data/logic/auth — AND zero Step-A high-risk triggers on the diff), **SKIP this Simplify phase** (quality-only; `ui-expert` already builds reuse-first) and Phase 3.7 Codex (per `codex-gate.md` § "Pure-graphics-card skip"). QA (Phase 3.5) is already skipped at `light` — the mechanical lint/tsc/build from Phase 2 step 8 is the "qa = build" floor. **Phase 2.6 `/e2e-review` is NOT skipped** — the fidelity trio (`markup-fidelity-verifier` + `visual-fidelity-verifier` + `ui-quality-critic`) is the real review for a graphics card. Doc-review (Phase 3) still runs (registry/spec reconciliation). Log `simplify/codex: SKIPPED (pure-graphics — fidelity trio is the review)`.
+
 After completeness is verified, clean up the implementation before it reaches reviewers and E2E tests. This phase launches three parallel agents on the card's diff, then applies fixes directly.
 
 **Step-by-step**:
@@ -156,6 +158,17 @@ The skill replaces the previous advisory pair (legacy Phase 2.6 E2E testing
 and Phase 2.7 visual design review). It runs by default on every UI card,
 auto-skips on backend-only cards, and BLOCKS the commit on gating findings.
 
+> **Route-independent, self-contained verification (since v4.78.0).** This card verifies
+> its **OWN** UI surface — it does NOT defer fidelity to a downstream card. `/e2e-review`
+> now runs a **route-free structural pass** (Phase 2.7, `markup-fidelity-verifier`: the
+> mockup's HTML/`design_src` code vs the implementation source) before any browser, so a
+> component card with no route of its own is still fully verifiable. Consequences for the
+> gating table below: a fidelity AC closes **only** on a real `passed` (a comparison was
+> performed) — a `skipped` does NOT close it, and a route that opened empty/degenerate
+> surfaces as `blocked` via `data-state-mismatch` / `coverage-gap`, never a silent pass.
+> A genuine cross-card fidelity deferral must go through the Phase 2.5b fidelity-AC
+> carve-out (explicit follow-up card), never a free-text note. This is the FEAT-0061 fix.
+
 #### Gate (skip the whole phase when any of the below is true)
 
 | Condition | Action |
@@ -206,7 +219,7 @@ When the gate above passes, the orchestrator invokes `/e2e-review` in
 | `status` from `/e2e-review` | Orchestrator action |
 |----|----|
 | `"passed"` | Log result in tracker. Proceed to Phase 3 (doc review + code review). |
-| `"skipped"` | Log skip reason. Proceed to Phase 3. |
+| `"skipped"` | Log skip reason. Proceed to Phase 3. **If the card has `links.design` / `links.design_src` yet the skill returned `skipped`, that is suspicious post-v4.78.0** (the route-free structural pass should have run): record `[E2E-FIDELITY-SKIP] <reason>` in `## Issues & Flags`, and do NOT mark any fidelity AC `[x]` on a skip — a fidelity AC closes only on a real `passed`. |
 | `"overridden"` | Log override + reason in `## Issues & Flags` as `[E2E-OVERRIDE] <reason>`. Proceed to Phase 3. |
 | `"blocked"` | **STOP the card**. Log findings in tracker + `## Issues & Flags` as `[E2E-BLOCKED] <count> gating findings (<categories>)`. Ask the user whether to (a) override with reason, (b) escalate (open follow-up card), or (c) abandon this card and continue the batch. Do NOT proceed to Phase 3 silently. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=none safe (a blocked E2E is a real gating failure) → take (b) escalate to a follow-up card; NEVER take (a) override autonomously.** |
 | `"error"` | Log error in `## Issues & Flags`. Ask the user whether to retry, skip, or abandon. Do NOT proceed silently. **Retry re-entry (defined path, capped):** on "retry", re-enter at step 1 of this Invocation contract — reset the `.baldart/e2e-review/<CARD-ID>/` state dir, re-spawn `/e2e-review` with the SAME payload, and re-parse. **Cap: 2 error-retries per card** (central repair cap, consistent with the other loops). On the 2nd `error`, do NOT re-offer "retry" — re-invoke `AskUserQuestion` with only skip/abandon, so the loop cannot recur unbounded. **When AUTONOMOUS, apply § AUTONOMOUS RESOLUTION RULE (SKILL.md): category=blocker; recommended=retry once (the capped re-entry above); if still `error` → skip the E2E for this card AND materialize a follow-up card to re-run it (NEVER abandon the card silently).** |

package/framework/agents/design-system-protocol.md

@@ -576,6 +576,84 @@ the most damaging case (a CSS-hidden heavy subtree) is invisible to a JS AST rul
 Rule 2 violations are HIGH; a viewport-scoped edit that mutates the other branch
 (rule 1) is MEDIUM.
 
+## Route-Independent Fidelity & Coverage Obligation (BLOCKING — SSOT)
+
+This is the single definition of how UI fidelity is verified per-card. `/e2e-review`,
+`/new` (implement + code-reviewer), `/ui-design`, and `/design-review` **cite** this
+section; they do not redefine it. The driving lesson (FEAT-0061): a fidelity check that
+depends on rendering a *live, data-bearing route* silently degrades to a pass when that
+route cannot render (auth-gated, empty database, wrong tenant) — a **skip masked as a
+pass**. The fix is to make verification **route-independent first** and to make an
+**un-runnable required check block, never pass**.
+
+### 1. Structural Fidelity (route-free) — runs FIRST
+
+When a card has a mockup expressed as code — `links.design` pointing to an **HTML**
+file, or `links.design_src` / `mockups/_src/` (finished Claude Design CODE, v4.75) — the
+**code-structural** comparison runs before any browser render, via the
+`markup-fidelity-verifier` agent. It compares the mockup's markup/CSS structure (grid vs
+flex, column count, element order, region presence, `@media` breakpoints) against the
+implementation source. This is the analogue of **tree-edit-distance over the DOM** — the
+*structural* dimension, complementary to the *perceptual* (pixel) dimension of
+`visual-fidelity-verifier`. It needs no browser, no auth, no data, and it deterministically
+catches the **2-column-mockup → 1-column-build** class of divergence. Its findings use the
+canonical severity taxonomy (SSOT in `visual-fidelity-verifier.md`); a structural
+`layout-break` is Critical. **Fixes route to `ui-expert`** (layout is the UI domain).
+
+### 2. Visual Fidelity — render as CONFIRMATION, route-independent where possible
+
+The pixel diff (`visual-fidelity-verifier`) confirms the structural result on a rendered
+image. The render source, in priority order: (a) **isolated render** of the surface via
+the `/ds-render` harness when it is a registry primitive (no route/auth/data needed);
+(b) the live-route screenshot when the route renders; (c) neither → a coverage obligation
+(below). The live-route screenshot is **not** the only fidelity source.
+
+### 3. State-aware Fidelity — `data-state-mismatch` (never compare a degenerate render)
+
+The render must reach the **data state the mockup depicts** (a populated table, a selected
+store/tenant). An empty-state / placeholder / error / wrong-context render of a route that
+HAS a mockup is a **`data-state-mismatch`** (Critical) — emitted by `visual-fidelity-verifier`,
+which sees the emptiness — **not** a silent skip or pass. The orchestrator owns *reaching*
+the depicted state via a bounded **reach-state loop**: project-specific recipes from the
+consumer's `.baldart/overlays/e2e-review.md` (`seed_data`, `select_populated_context`,
+`goto_populated_entity`), with generic fallbacks (real auth from the persona creds,
+MSW/API-mock, deterministic factory/snapshot, heuristic context auto-seek). The framework
+owns the contract + the loop; the overlay owns the project-specific *how*.
+
+### 4. Coverage Obligation — `coverage-gap` (un-runnable required check BLOCKS)
+
+A required fidelity check that **could not execute at all** must block, never pass. The
+orchestrator synthesizes a **`coverage-gap`** (Critical) finding when an **image-only**
+mockup exists (`mockup_source.level ∈ {figma, local}`, i.e. no HTML/code to diff
+structurally) AND neither an isolated render nor a route render produced a comparable
+screenshot, AND the state could not be reached. **Guards (never fire `coverage-gap`):**
+`mockup_source.level == skip` (no mockup → no obligation), `harness-render` (assertion-fitting
+guard — these go to quality only), `compliance-only` (registry-based, no image target), and
+the mobile responsive pass (runs at `level: skip` by construction). A `coverage-gap` is
+**not fixable by an agent** (the route still will not render) — it **bypasses the self-heal
+loop** and maps to the existing `blocked` verdict (the orchestrator's autonomous handling
+escalates it to a follow-up card). No new verdict status is introduced.
+
+### 5. Graphics-only card → `ui-expert` + the fidelity trio IS the review
+
+For a **pure-graphics card** (`owner_agent: ui-expert`, `review_profile: light`,
+`areas == [ui]` exactly — no api/data/logic/auth), the implementer is `ui-expert` (not
+`coder`), and the **fidelity trio is the review**: `markup-fidelity-verifier` (structure)
++ `visual-fidelity-verifier` (pixels + a11y) + `ui-quality-critic` (intrinsic quality,
+advisory), plus the mechanical build/lint/tsc gates. The deep `/codexreview` and
+`simplify` passes are skipped — their UI-relevant coverage (a11y, token-bypass, DS-drift,
+layout) is absorbed by the trio. All fidelity fixes (structural, presentational, quality)
+route to `ui-expert`.
+
+### Gating philosophy (calibration)
+
+Vision-model reliability research (*MLLM as a UI Judge*, 2025) shows multimodal judges are
+reliable at **comparison with clear differences** (~93%) but weak at **absolute scoring**
+(~35% exact, hedging toward low variance). Therefore the **hard gate is FIDELITY**
+(comparison against a ground truth: structural + visual), and **intrinsic-quality absolute
+scoring (`ui-quality-critic`) stays advisory / confidence-gated**, never a hard block. The
+2-col → 1-col case is a "clear difference" → maximum judge reliability.
+
 ## Post-Intervention Coherence Check (BLOCKING completion gate)
 
 The BLOCKING pre-work above enforces *reads* before any UI change. This

package/framework/templates/overlays/e2e-review.fidelity-example.md

@@ -0,0 +1,74 @@
+---
+base_skill: e2e-review
+base_skill_version: 4.78.0
+mode: extend
+---
+
+# e2e-review — fidelity-app overlay (example)
+
+> Project-specific **reach-state recipes** for `/e2e-review` Phase 3.8. The framework
+> owns the contract and the bounded loop; this overlay tells the orchestrator HOW to put
+> the app into the data state a mockup depicts, so the visual reviewer never compares a
+> degenerate (empty / wrong-tenant / error) render. Drop into
+> `.baldart/overlays/e2e-review.md` and adapt to your stack.
+>
+> Without these recipes `/e2e-review` falls back to generic remediation (real auth from
+> the persona creds, MSW/API-mock, deterministic factory/snapshot, heuristic context
+> auto-seek) and, failing that, **blocks** with `coverage-gap` — it never silently passes
+> an empty render.
+
+## [APPEND] Reach-state recipes
+
+The orchestrator runs the applicable recipes in order until `render_health.degenerate`
+is false. Each recipe is a named, deterministic sequence of steps the orchestrator can
+execute via Playwright / `webapp-testing` / a project script. Cap: 2 attempts.
+
+### `seed_data` — populate the database for the route
+
+Run before navigating, when the route shows an empty-state because the demo/CI database
+is empty:
+
+```bash
+# Example: seed a deterministic dataset the mockup depicts (idempotent).
+npm run db:seed:e2e            # creates store "demo" + ≥3 products + 1 supplier
+```
+
+State guarantee: after this, `/products` renders a populated table matching the mockup's
+DATI PRODOTTO / FORNITORI sections. The seed MUST be deterministic (fixed ids, no
+faker-without-seed) so screenshots are reproducible.
+
+### `select_populated_context` — the multi-store / multi-tenant case
+
+When the default-selected store/tenant is empty but another has data (the exact failure
+the user flagged): switch context to a populated one before screenshotting.
+
+```
+1. Authenticate as the owner persona (test_plan.test_credentials).
+2. Open the store switcher: getByRole("button", { name: /store|negozio/i }).
+3. Pick the first store whose product count > 0 (the seeded "demo" store), NOT the
+   default empty one.
+4. Wait for networkidle, then proceed to the route.
+```
+
+Heuristic fallback (no explicit list): enumerate the switcher options, navigate the route
+under each, and pick the first that yields non-empty content (the verifier confirms
+non-emptiness). This is the generic `webapp-testing` auto-seek.
+
+### `goto_populated_entity` — detail routes that need a specific id
+
+When the mockup depicts a specific entity (e.g. a product detail), navigate to a seeded
+entity id rather than a random/empty one:
+
+```
+Navigate to `/products?selected=<seeded-product-id>&edit=1` (the id created by
+`seed_data`), not the bare `/products`.
+```
+
+## [APPEND] Notes
+
+- Recipes are tried in the order above (`seed_data` → `select_populated_context` →
+  `goto_populated_entity`); a recipe that does not apply to a route is a no-op.
+- Keep recipes **deterministic and idempotent** — they run inside the bounded reach-state
+  loop and may be re-invoked across self-heal iterations.
+- A recipe MUST NOT mutate production data: scope to the e2e/demo database the dev server
+  uses. The framework's contract assumes an isolated test database.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.77.0",
+  "version": "4.78.1",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"