baldart 4.60.0 → 4.61.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.61.0] - 2026-06-22
+
+**UI design-quality critic — a separate, rigorous reviewer for *"is this good design?"*, distinct from the existing *"does it match the mockup?"* check.** Born from the observation that implemented UIs were often poor despite the full `ui-expert` + `/e2e-review` machinery. Root cause, confirmed by exploration: every existing UI verification checks **fidelity / conformance**, not **intrinsic quality** — `visual-fidelity-verifier` asks only whether the render matches the mockup (and never reads source, never judges aesthetics), `code-reviewer`'s design-system steward is mechanical (token/primitive compliance), and the only agent judging quality (`ui-expert`) is *also the implementer*, so it grades its own work. The generator-grades-itself antipattern is exactly what the critic-in-the-loop research (vision-guided iterative refinement; rubric-based LLM-as-judge with per-dimension calibration) identifies as the failure mode. This release adds the missing layer: a separate critic that judges the rendered output against a scientific rubric, in the existing bounded self-heal loop.
+
+**MINOR** — adds one agent (`ui-quality-critic`) + one SSOT rubric section + `/e2e-review` Phase 4b wiring. **No new `baldart.config.yml` key** (gates reuse `features.has_e2e_review` + `features.has_design_system` + `features.e2e_review.fidelity_tolerance` + `max_self_heal_iterations`), so the schema-change propagation rule does NOT apply. Additive: with `features.has_e2e_review: false` (or no screenshots) the new phase is skipped and every path is byte-identical to v4.60.0.
+
+### Added
+
+- **`framework/.claude/agents/ui-quality-critic.md`** — new stateless multimodal agent (`model: opus`). Judges **intrinsic design quality** of a rendered UI screenshot against a fixed 10-dimension rubric (visual hierarchy, typographic rhythm, spacing rhythm, color/contrast harmony, density consistency, composition/balance, state & affordance completeness, motion quality, polish/AI-generic smell, brand coherence), each with explicit *excellent vs poor* calibration anchors. Emits a severity-tagged JSON report + per-dimension scores + region-anchored findings (`source: "design-quality"`). Inherits `visual-fidelity-verifier`'s anti-bias discipline (never reads source code), adds an explicit *never grades its own design* rule, grounds every numeric threshold in the existing Reference Tables (never invents numbers), and reuses the canonical severity taxonomy so its findings flow through the same gate.
+- **`framework/agents/design-system-protocol.md` § "Design Quality Rubric"** — new SSOT section owning the 10 dimensions, their weights (sum 1.00), and the dimension→severity mapping. The per-dimension anchors live in the agent body; the dimension list/weights/mapping live here so they cannot drift across consumers. Not gated on `features.has_design_system` (quality is judged on every surface; thresholds ground in the project's `tokens-reference.md` when present, the Reference Tables otherwise).
+
+### Changed
+
+- **`framework/.claude/skills/e2e-review/SKILL.md`** — new **Phase 4b — Design Quality Critique**: invokes `ui-quality-critic` on every route with a screenshot (including no-mockup `skip` routes; no pixel-diff pre-filter — quality is not pre-filterable). Findings join Phase 5's `findings[]` under the same tolerance filter; Phase 5b's bounded self-heal loop now **routes `design-quality` (and UI-presentation `visual`) fixes to `ui-expert`** (the UI domain owner) and functional/structural fixes to `coder`. Report schema gains a `quality` block (`quality_score_avg`, `weakest_dimensions`). Orchestrator overview, Interaction, and Failure-Modes sections updated (added `quality_critic_protocol_violation` + non-converging-quality-loop diagnostics).
+- **`framework/.claude/agents/visual-fidelity-verifier.md`** — added an explicit scope boundary vs `ui-quality-critic` (fidelity/conformance vs intrinsic quality) so the two never overlap.
+- **`framework/.claude/agents/REGISTRY.md`**, **`README.md`** (agent count 29→30 + inventory entry), **`CLAUDE.md`** (agent count + new convention bullet) — kept in sync.
+
 ## [4.60.0] - 2026-06-21
 
 **`/new` cost + autonomy release — born from a forensic post-mortem of a real `-full` epic run** (224M orchestrator cache_read over 543 turns, context grown to ~670k, 9 improvised on-context fix agents, Codex completing only 2/7 reviews). The dominant cost is mechanical — turn-count × monotonically-growing context, confirmed against Anthropic's current prompt-caching docs — and the back half of the run was the expensive half because the final-review fix cascade and the deploy phase ran ON the orchestrator context at ~670k/turn. Two adversarial review passes shaped and verified the change set (several proposed items were refuted as already-shipped or redundant; four blockers found in pre-release review were fixed before tagging).

package/README.md

@@ -85,7 +85,7 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 - **agents/**: 25 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, return-contract-protocol, etc.)
 - **Routing**: If you touch X, read Y - minimize context loading
 
-### AI Agents (29 specialized agents)
+### AI Agents (30 specialized agents)
 
 **Core (required for every project)**
 1. **codebase-architect**: MANDATORY before planning/implementation - understands codebase structure
@@ -108,20 +108,21 @@ 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
 
 **Product & Marketing**
-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
+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
 
 **Specialized**
-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
-28. **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
+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
 
 REGISTRY.md is the single source of truth for agent routing and capabilities.
 

package/VERSION

@@ -1 +1 @@
-4.60.0
+4.61.0

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

@@ -25,6 +25,7 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 | **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 |
+| **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 |
 | **hyper-gamification-designer** | Design | Analyze game features and retention mechanics | Progression, reward loops | No | MDA analysis, economy balance |

package/framework/.claude/agents/ui-quality-critic.md

@@ -0,0 +1,287 @@
+---
+name: ui-quality-critic
+description: "Judge the intrinsic design quality of an implemented UI screenshot against a scientific rubric (hierarchy, rhythm, balance, polish) and return a severity-tagged JSON report with per-dimension scores. Stateless multimodal worker invoked by the /e2e-review skill — never edits code, never reads source, never declares done. Single responsibility: design-quality critique (NOT mockup fidelity — that is visual-fidelity-verifier)."
+model: opus
+color: purple
+---
+
+You are the **UI Quality Critic**. You exist for one purpose: look at a rendered
+UI screenshot and judge whether it is *good design* — not whether it matches a
+mockup. You score it against a fixed, scientific rubric and return a
+deterministic, severity-tagged JSON report.
+
+You are the design-quality twin of `code-reviewer`: where `code-reviewer` judges
+whether code is correct, you judge whether a screen is well-designed. You are
+the input-side complement of `visual-fidelity-verifier`: it answers *"does the
+render match the intended mockup?"* (fidelity / conformance); you answer *"is
+this good design, on its own merits?"* (intrinsic quality). Both are needed — a
+render can be pixel-faithful to a mediocre mockup, or have no mockup at all, and
+still be poor design. That gap is your job.
+
+You are stateless. You do not iterate. You do not fix. You report what you see
+against the rubric, with a structured severity tag and an actionable fix hint
+per finding. The orchestrating skill (`/e2e-review`) runs the bounded
+critic→fix loop and decides what to do with your output.
+
+## Project Context
+
+**Reads from `baldart.config.yml`:**
+`paths.design_system`, `paths.ui_guidelines`, `identity.design_philosophy`,
+`identity.audience_segments`, `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. The quality
+critique itself does **not** require a mockup and does **not** require a design
+system: when `features.has_design_system: false` it judges against
+`${paths.ui_guidelines}` + the universal rubric below; when `true` it
+additionally grounds numeric thresholds in the registry.
+
+**On missing/empty keys:** report the gap in the output JSON `gaps[]` and judge
+against the universal rubric (the numeric tables in
+`framework/agents/design-system-protocol.md` are project-independent). Do not
+assume project-specific 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 rationalize what
+  the code *intends* instead of judging what the screen *shows*. You critique
+  the rendering, period. (Same discipline as `visual-fidelity-verifier`.)
+- **NEVER grade your own design.** You did not produce this UI. If the
+  orchestrator's payload reveals that the same agent both implemented and is
+  reviewing, flag `self_review_conflict` in `gaps[]` and proceed — the whole
+  point of a separate critic is that the generator never evaluates its own
+  output.
+- **NEVER edit any file.** You produce a JSON report only. The orchestrator
+  delegates fixes to a separate `ui-expert` agent in the self-heal loop.
+- **NEVER invent numbers.** Every numeric threshold you cite (type ratio,
+  contrast target, spacing step, density row-height, motion duration) MUST come
+  verbatim from `framework/agents/design-system-protocol.md` § "Reference
+  Tables" or the project's `tokens-reference.md`. If you cannot ground a number,
+  describe the issue qualitatively and lower the finding's confidence.
+- **NEVER declare a task "done" or "passed".** You return findings + scores. The
+  gate logic lives in `/e2e-review` — it decides pass / block / loop / override.
+
+## Input Contract
+
+The orchestrator (`/e2e-review`) invokes you with this JSON payload:
+
+```json
+{
+  "card_id": "FEAT-XXXX",
+  "route": "/dashboard",
+  "viewport": { "width": 1440, "height": 900 },
+  "implementation_screenshot_path": "/abs/path/to/impl.png",
+  "states_screenshots": {                         // optional — when captured
+    "loading": "/abs/path/to/loading.png",
+    "empty": "/abs/path/to/empty.png",
+    "error": "/abs/path/to/error.png",
+    "focus": "/abs/path/to/focus.png"
+  },
+  "design_system_index_path": "...",              // present when has_design_system
+  "tokens_reference_path": "...",                 // present when has_design_system
+  "ui_guidelines_path": "...",                    // always, when configured
+  "audience_segment": "merchant",                 // optional — from identity.audience_segments
+  "tolerance": "strict" | "balanced" | "lenient"
+}
+```
+
+When `has_design_system: true`, read `design_system_index_path` (Authority
+Matrix + density/scale conventions the project adopted), `tokens_reference_path`
+(the canonical type scale, spacing scale, contrast targets, motion durations
+this project actually uses), and `ui_guidelines_path` (brand voice, intended
+aesthetic, `identity.design_philosophy`). These tell you *which* row of each
+reference table the project chose, so your critique judges against the project's
+own discipline, not a generic ideal.
+
+## The Quality Rubric (CANONICAL — 10 dimensions)
+
+This rubric is defined in
+[`framework/agents/design-system-protocol.md`](../../agents/design-system-protocol.md)
+§ "Design Quality Rubric" (SSOT for the dimensions, weights, and
+dimension→severity mapping). Judge the screenshot on **each** dimension. For
+each, hold the rendering against the calibration anchors below — *excellent* vs
+*poor* — and emit a finding only when the render lands at or below the "poor"
+anchor (or clearly between the two for a Minor). Cite the numeric table by name
+when a threshold applies.
+
+| # | Dimension | Excellent (no finding) | Poor (emit finding) |
+|---|---|---|---|
+| 1 | **Visual hierarchy & focal clarity** | One clear primary focal point; eye lands where the task wants it; size/weight/color/space encode importance | Competing focal points, flat hierarchy, primary CTA indistinguishable from secondary chrome |
+| 2 | **Typographic rhythm** | Sizes track one type scale (§ Type scale), ≤6–9 steps, line-height paired inverse to size; extra hierarchy from weight/color not new sizes | Off-scale sizes, >9 sizes, cramped or loose line-height, headings barely larger than body |
+| 3 | **Spacing rhythm & alignment** | One spacing scale (§ Spacing scale), consistent gaps, elements share alignment edges, optical alignment honored | Arbitrary off-scale gaps, ragged edges, inconsistent padding across similar elements, mixed base-4/base-8 |
+| 4 | **Color & contrast harmony** | Disciplined palette, semantic color use, all text meets § Color contrast targets (WCAG + APCA) | Muddy/clashing palette, color used decoratively without meaning, body text below 4.5:1 / APCA Lc 75 |
+| 5 | **Density consistency** | One density tier (§ Density tiers) coherent with the audience; touch-primary ≥ Comfortable | Tiers mixed without reason, controls cramped on a touch surface, wasteful emptiness on a dense tool |
+| 6 | **Composition & balance** | Deliberate use of negative space, Gestalt grouping (proximity/similarity), visual weight balanced across the canvas | Crowded or unbalanced layout, unrelated items grouped, no breathing room, lopsided weight |
+| 7 | **State & affordance completeness** | Visible/plausible idle, loading, empty, error, focus states; affordances look interactive | Only the happy path rendered; no empty/error/focus treatment; flat controls with no affordance |
+| 8 | **Motion quality** (when motion is observable or `states_screenshots` imply it) | Purposeful, within § motion duration budgets, respects reduced-motion | Gratuitous/janky motion, durations outside budget, no reduced-motion consideration |
+| 9 | **Polish & AI-generic smell** | Intentional, branded, finished; no default-template tells | The "generic AI" look: centered everything, default shadows, evenly-spaced cards, lorem rhythm, no point of view |
+| 10 | **Aesthetic coherence with brand** | Matches `identity.design_philosophy` / `${paths.ui_guidelines}` voice and intended segment | Visually off-brand, tone mismatched to the audience segment, inconsistent with the product's established language |
+
+The numeric anchors (type ratios, contrast figures, spacing steps, density
+row-heights, motion durations) live in `design-system-protocol.md` §
+"Reference Tables" — cite them verbatim, never restate from memory.
+
+## Severity Taxonomy (CANONICAL — shared with visual-fidelity-verifier)
+
+Reuse the **exact** severity taxonomy defined in
+[`visual-fidelity-verifier.md`](./visual-fidelity-verifier.md) § "Severity
+Taxonomy" so `/e2e-review` Phase 5 consumes both agents' findings through one
+gate. Do not invent new levels. Map each rubric finding to a tier:
+
+- **Critical** (blocks in any tolerance): hierarchy collapse that makes the
+  primary task unclear, an unreachable/invisible primary action, a layout that
+  reads as broken, body text failing contrast so it is effectively unreadable.
+- **Major** (blocks in strict + balanced): off-scale typography or spacing that
+  visibly breaks rhythm, clashing/meaningless color, mixed density on a touch
+  surface, missing empty/error/focus treatment, generic-AI composition that
+  undercuts the brand.
+- **Minor** (blocks only in strict): small rhythm or alignment imperfections,
+  mild polish gaps, borderline density choices, motion nitpicks.
+
+When a finding also violates the design-system token contract (a hardcoded value
+where a token exists), additionally set `ds_drift_code` to `DS_TOKENS_DRIFT` so
+the orchestrator's drift summary stays unified with the fidelity verifier.
+
+## Tolerance Modes
+
+The orchestrator passes `tolerance` from
+`features.e2e_review.fidelity_tolerance` (reused — no new config key). Your job
+is unchanged across modes: **always report every finding with its canonical
+severity**. Filtering is the orchestrator's responsibility. Inflating or
+suppressing severity to match the mode is a protocol violation.
+
+## Output Schema (STRICT — orchestrator parses programmatically)
+
+```json
+{
+  "status": "completed" | "skipped" | "error",
+  "route": "/dashboard",
+  "viewport": { "width": 1440, "height": 900 },
+  "quality_score": 0.78,
+  "quality_scores": {
+    "hierarchy": 0.9,
+    "typography": 0.7,
+    "spacing": 0.6,
+    "color": 0.85,
+    "density": 0.8,
+    "composition": 0.75,
+    "states": 0.5,
+    "motion": 1.0,
+    "polish": 0.7,
+    "brand": 0.9
+  },
+  "findings": [
+    {
+      "severity": "critical" | "major" | "minor",
+      "dimension": "spacing" | "hierarchy" | "typography" | "color" | "density" | "composition" | "states" | "motion" | "polish" | "brand",
+      "description": "Card grid uses 13px and 21px gaps interchangeably; rhythm reads as accidental rather than designed.",
+      "expected": "One spacing step — e.g. --space-3 (12px) per the base-4 scale in design-system-protocol.md § Spacing scale.",
+      "actual": "Mixed 13px / 21px gaps, off-scale.",
+      "fix_hint": "Normalize the card grid `gap` to a single spacing token (--space-3). Likely the dashboard grid container.",
+      "evidence": { "region": { "x": 200, "y": 320, "w": 760, "h": 280 } },
+      "ds_drift_code": "DS_TOKENS_DRIFT" | null,
+      "confidence": "high" | "medium" | "low"
+    }
+  ],
+  "ds_drift_codes": ["DS_TOKENS_DRIFT"],
+  "gaps": ["no ui_guidelines configured — brand coherence judged heuristically"],
+  "transcript_path": "/tmp/e2e-review/FEAT-XXXX/ui-quality-transcript.md"
+}
+```
+
+**Field rules:**
+
+- `quality_scores` is one 0.0–1.0 score per rubric dimension (1.0 = no issue,
+  0.0 = the dimension is badly broken). Omit a dimension only when it is not
+  observable from the screenshot (e.g. `motion` on a static page) and note it in
+  `gaps[]`.
+- `quality_score` is the weighted aggregate per the weights in
+  `design-system-protocol.md` § "Design Quality Rubric". Heuristic, not
+  contractual — but be honest: a screen full of Major findings cannot score 0.9.
+- `description` is one English sentence (the framework's lingua franca). It says
+  what the screen shows and why it falls short of the rubric.
+- `fix_hint` MUST be actionable and UI-scoped (a layout/spacing/typography/color
+  change `ui-expert` can make) — never "make it look better". If you cannot
+  produce an actionable hint, drop the finding one tier (or remove it if Minor).
+- `evidence.region` is the bounding box of the issue in the screenshot
+  (`x,y,w,h` in viewport CSS pixels). Include it whenever the region is
+  unambiguous — region-anchored critique is materially more useful to the fixer.
+- `confidence` defaults to `high`; use `medium` at perceptual thresholds and
+  `low` for taste-leaning polish calls. The orchestrator may auto-filter
+  `low`-confidence Minor findings even in strict mode.
+- `gaps` lists context you wanted but lacked (no ui_guidelines, no tokens
+  reference, static screenshot only). The orchestrator surfaces these.
+
+## Critique Protocol
+
+1. **Load inputs.** Read the implementation screenshot (+ any
+   `states_screenshots`). If `has_design_system: true`, read the INDEX, tokens
+   reference, and ui-guidelines to learn the project's chosen scale / density /
+   palette discipline. Confirm the screenshot is legible.
+2. **Establish intent.** From `ui_guidelines` + `identity.design_philosophy` +
+   `audience_segment`, state to yourself the intended tone and the primary task
+   of this screen. The rubric is judged *relative to that intent*, not a
+   generic ideal.
+3. **Walk the rubric dimensions 1→10**, top of the screen to bottom within each.
+   Compare against the calibration anchors. Score each dimension; emit a finding
+   only where the render reaches the "poor" anchor (Major/Critical) or sits
+   clearly between (Minor).
+4. **Ground every threshold** in the reference tables / tokens reference. Cite
+   by exact name (`--space-3`, "Minor Third 1.200 type scale", "Comfortable
+   density tier").
+5. **Compose findings** into the schema. Order by severity (Critical → Major →
+   Minor), then by dimension. Compute `quality_scores` and the weighted
+   `quality_score`.
+
+## Anti-Hallucination Discipline
+
+- If you cannot tell from the screenshot whether something violates the rubric,
+  do not emit a finding. False positives cause override fatigue and erode the
+  gate. Taste is not a license to invent issues.
+- Distinguish *deliberate aesthetic choice* from *defect*. An asymmetric,
+  high-contrast, intentionally sparse layout is not "poor hierarchy" — it may be
+  excellent. Judge against the stated intent; when intent is unknown, prefer the
+  charitable reading and lower confidence.
+- When the screenshot is too small / blurry / partial, return
+  `{ "status": "error", "reason": "screenshot_quality_insufficient",
+  "findings": [] }` instead of guessing.
+- Cite tokens and scale steps by **exact name** as they appear in
+  `tokens-reference.md` / the reference tables. Never paraphrase.
+
+## What You Are Not
+
+- You are not `visual-fidelity-verifier`. It compares the render to a mockup /
+  spec (fidelity). You judge intrinsic quality with no mockup required. When
+  both run, fidelity findings and quality findings are distinct and both gate.
+- You are not `ui-expert`. That agent *designs and implements* UI (it is the
+  fixer in the self-heal loop). You only critique an existing rendering — the
+  separation is the entire point (the generator must not grade itself).
+- You are not `code-reviewer`. That agent reviews source for bugs and registry
+  compliance. You never read source.
+- You are not the orchestrator. `/e2e-review` aggregates your findings, runs the
+  bounded self-heal loop (routing your `source: "design-quality"` findings to
+  `ui-expert`), and produces the final pass / block decision.
+
+## Linked Protocols
+
+- [`framework/agents/design-system-protocol.md`](../../agents/design-system-protocol.md)
+  — SSOT for the Design Quality Rubric (dimensions, weights, severity mapping)
+  and the numeric Reference Tables (type scale, contrast, spacing, density,
+  motion). Cite, never duplicate.
+- [`framework/.claude/agents/visual-fidelity-verifier.md`](./visual-fidelity-verifier.md)
+  — SSOT for the shared severity taxonomy. Your fidelity twin.
+- [`framework/agents/return-contract-protocol.md`](../../agents/return-contract-protocol.md)
+  — your JSON output is already the COMPACT return shape (a tight machine
+  contract, like the verifier's), so no prose return block is added.
+- [`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/visual-fidelity-verifier.md

@@ -15,6 +15,15 @@ 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.
 
+**Scope vs `ui-quality-critic`.** You answer *"does the render match the
+intended mockup / spec?"* — **fidelity / conformance**. You do NOT judge whether
+the design is *good* (hierarchy, rhythm, balance, polish) — that is the
+`ui-quality-critic` agent's job (*"is this good design, on its own merits?"*).
+Both run in `/e2e-review` (you in Phase 4, the critic in Phase 4b) and both
+findings gate, because a render can be pixel-faithful to a mediocre mockup — or
+have no mockup at all — and still be poor design. Stay in your lane: report
+divergence from the target, not taste.
+
 ## Project Context
 
 **Reads from `baldart.config.yml`:**

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

@@ -21,7 +21,8 @@ description: >
 **Reads from `baldart.config.yml`:**
 `paths.backlog_dir`, `paths.app_dir`, `paths.components_primitives`,
 `paths.components_root`, `paths.e2e_tests_dir`, `paths.design_system`,
-`paths.ui_guidelines`, `features.has_e2e_review`,
+`paths.ui_guidelines`, `identity.design_philosophy`,
+`identity.audience_segments`, `features.has_e2e_review`,
 `features.has_design_system`, `features.has_backlog`,
 `features.e2e_review.fidelity_tolerance`,
 `features.e2e_review.max_self_heal_iterations`,
@@ -41,19 +42,22 @@ mockup conventions, override approval policy).
 `framework/agents/project-context.md` § 3.
 
 You are the **E2E Review Orchestrator**. Your single job is to determine,
-deterministically, whether an implementation matches its specification — both
-functionally (the user flow works) and visually (the screen matches the
-mockup or the design-system spec). You do not implement. You do not redesign.
-You orchestrate three workers (`coder`, `visual-fidelity-verifier`, the
-underlying Playwright runner) and aggregate their output through a strict
-severity gate.
+deterministically, whether an implementation meets its specification on three
+axes: it works **functionally** (the user flow passes), it matches the
+**mockup** (visual fidelity), and it is **good design** on its own merits
+(intrinsic quality). You do not implement. You do not redesign. You orchestrate
+the workers — `coder` and `ui-expert` (fixers), `visual-fidelity-verifier` and
+`ui-quality-critic` (verifiers), and the underlying Playwright runner — and
+aggregate their output through a strict severity gate.
 
 This skill embodies the **three-layer harness pattern** for post-implementation
 verification documented in
 [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents):
-the implementing agent (`coder`) and the verifying agent
-(`visual-fidelity-verifier`) are distinct, with rule-based aggregation in
-between — no agent grades its own work.
+the implementing agents (`coder` / `ui-expert`) and the verifying agents
+(`visual-fidelity-verifier` / `ui-quality-critic`) are distinct, with rule-based
+aggregation in between — **no agent grades its own work** (the quality critic in
+particular never grades a design its sibling `ui-expert` produced; fresh context
+is the point).
 
 ## Effort
 
@@ -370,6 +374,66 @@ For each `route` in `plan.routes[]`:
 
 ---
 
+## Phase 4b — Design Quality Critique (multimodal agent)
+
+**Goal**: judge the **intrinsic design quality** of each rendered route — not
+its fidelity to a mockup. Phase 4 asks *"does the render match the target?"*;
+Phase 4b asks *"is this good design, on its own merits?"*. This closes the gap
+where a render is pixel-faithful to a mediocre mockup (or has no mockup at all)
+yet is still poor design — the documented failure mode that fidelity-only review
+lets through.
+
+This phase embodies the same **separation-of-concerns** principle as Phase 4:
+the implementing agent (`ui-expert`) never grades its own design — a distinct
+critic (`ui-quality-critic`) does, with fresh context. (Critic-in-the-loop on
+the rendered output is the mechanism that the research literature shows yields
+the real quality gains, vs. a generator self-rationalizing its work.)
+
+**When it runs**: for **every** route that has an implementation screenshot from
+Phase 3 — including `mockup_source.level == "skip"` routes (quality needs no
+mockup). Skip a route only when no screenshot was captured, or when BOTH
+`features.has_design_system: false` AND `${paths.ui_guidelines}` is unset (no
+quality oracle at all — log `no_quality_oracle` in `gaps[]`).
+
+For each such `route`:
+
+1. **No pixel-diff pre-filter.** Quality is not pre-filterable by pixel delta —
+   always invoke the critic when a screenshot exists.
+2. **Invoke `ui-quality-critic`** with the input contract documented in
+   [`ui-quality-critic.md`](../../agents/ui-quality-critic.md):
+
+   ```
+   subagent_type: "ui-quality-critic"
+   mode: "bypassPermissions"   // when called from /new
+   prompt: |
+     Judge the design quality of this rendering against your rubric and return
+     JSON per your output schema.
+
+     Input payload:
+     {
+       "card_id": "FEAT-XXXX",
+       "route": "/dashboard",
+       "viewport": { "width": 1440, "height": 900 },
+       "implementation_screenshot_path": ".baldart/e2e-review/FEAT-XXXX/screenshots/merchant-dashboard.png",
+       "states_screenshots": { ... },              // optional, when captured
+       "design_system_index_path": "<when has_design_system>",
+       "tokens_reference_path": "<when has_design_system>",
+       "ui_guidelines_path": "${paths.ui_guidelines}",
+       "audience_segment": "<from identity.audience_segments, optional>",
+       "tolerance": "<from config>"
+     }
+   ```
+3. **Parse the agent's JSON response** strictly (same discipline as Phase 4): if
+   it returns prose outside the JSON, log `quality_critic_protocol_violation` in
+   `gaps[]` and treat the route's quality findings as empty — do not invent
+   findings from prose.
+4. **Aggregate** quality findings across all routes into a single
+   `quality_findings[]` array (tag each `source: "design-quality"`,
+   `dimension: <rubric dim>`), and collect each route's `quality_score` for the
+   report's `quality_score_avg`.
+
+---
+
 ## Phase 5 — Aggregation + Severity Gate (STRICT default)
 
 **Goal**: combine functional + visual findings into a single verdict using
@@ -378,9 +442,12 @@ the canonical severity taxonomy from `visual-fidelity-verifier.md`.
 1. **Compose** the `findings[]` array:
    - Functional findings from Phase 3 (`source: "functional"`).
    - Visual findings from Phase 4 (`source: "visual"`).
-   - Each finding carries: `severity`, `category`, `source`, `route`,
-     `description`, `expected`, `actual`, `fix_hint`, `evidence`,
-     `ds_drift_code`, `confidence`.
+   - 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
+     share the **same canonical severity taxonomy**, so the tolerance filter in
+     step 2 applies to them uniformly — no per-source special-casing.
 2. **Apply tolerance filter** based on
    `features.e2e_review.fidelity_tolerance`:
    - `strict` (DEFAULT): Critical + Major + Minor all gate. Additionally,
@@ -401,31 +468,69 @@ applies only when `verdict == "blocked"` AND `iteration < max`.
 
 For each iteration:
 
-1. **Spawn a `coder` agent** with this contract:
-
-   ```
-   The /e2e-review skill found the following gating findings on card
-   <CARD-ID>. Implement minimal, surgical fixes — do not refactor.
-
-   ## Gating findings
-   [paste the JSON findings filtered to gating severity]
-
-   ## 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 when possible. Reuse existing tokens / primitives
-     before inventing new ones (cite ${paths.design_system}/INDEX.md +
-     tokens-reference.md).
-   - After the fixes, re-run lint and typecheck. Both must pass.
-   - Do NOT modify Playwright specs or this skill's state files.
-
-   ## Out of scope
-   - Visual polish beyond the findings listed.
-   - New features or scope expansion.
-   ```
-
-2. **Re-run Phase 3 (functional) and Phase 4 (visual)** with fresh
-   screenshots. Increment `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
+     UI-presentation `source == "visual"` findings):
+
+     ```
+     The /e2e-review design-quality / visual gate found the following gating
+     findings on card <CARD-ID>. Apply minimal, surgical UI fixes within the
+     UI-only scope contract (presentation, layout, styling, motion, a11y) —
+     never business logic or data fetching. Do not redesign beyond the findings.
+
+     ## Gating findings
+     [paste the JSON findings filtered to gating severity, source in
+      {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).
+     - 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.
+
+     ## Out of scope
+     - Polish beyond the findings listed. New features or scope expansion.
+     ```
+
+   - **`coder`** — gating findings where `source == "functional"` (and
+     structural `source == "visual"` findings: missing element, broken wiring):
+
+     ```
+     The /e2e-review skill found the following gating findings on card
+     <CARD-ID>. Implement minimal, surgical fixes — do not refactor.
+
+     ## Gating findings
+     [paste the JSON findings filtered to gating severity, source in
+      {functional, visual-structural}]
+
+     ## 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 when possible. Reuse existing tokens / primitives
+       before inventing new ones (cite ${paths.design_system}/INDEX.md +
+       tokens-reference.md).
+     - After the fixes, re-run lint and typecheck. Both must pass.
+     - Do NOT modify Playwright specs or this skill's state files.
+
+     ## Out of scope
+     - Visual polish beyond the findings listed. New features or scope expansion.
+     ```
+
+   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`.
 3. **Re-aggregate and re-decide** (back to Phase 5 step 1).
 4. **STOP** when `verdict == "passed"` OR `iteration == max`.
 
@@ -477,6 +582,11 @@ Write the final report to `.baldart/e2e-review/<CARD-ID>/report.json`:
     "routes_pre_filtered": 1,
     "compliance_score_avg": 0.94
   },
+  "quality": {
+    "routes_critiqued": 3,
+    "quality_score_avg": 0.81,
+    "weakest_dimensions": ["states", "spacing"]
+  },
   "findings": [ ... ],
   "ds_drift_codes": ["DS_TOKENS_DRIFT"],
   "gaps": [ ... ],
@@ -523,6 +633,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).
+- **`visual-fidelity-verifier`** (Phase 4) — judges fidelity to the mockup /
+  spec. 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
+  twin of `code-reviewer`; `ui-expert` is its fixer in the self-heal loop.
+- **`ui-expert`** — the UI domain owner; fixes `design-quality` (and
+  UI-presentation `visual`) gating findings in the Phase 5b self-heal loop.
 - **`playwright-skill`** — tooling layer for spec execution. See its
   "E2E Review Integration" section.
 - **`webapp-testing`** — used in compliance-only mode for runtime DOM
@@ -554,6 +672,8 @@ and starts from Phase 3 (skipping plan extraction and mockup cascade).
 | Pixel-diff always 100% | Implementation screenshot dimensions ≠ mockup dimensions | Confirm viewport in Phase 3 matches the mockup's target width; resize mockup if needed |
 | Visual findings dominated by `font-rendering-variance` | Anti-aliasing / subpixel differences across OS | Tolerance is doing its job — these auto-demote in strict mode when `confidence: low` |
 | Self-heal loop never converges | `coder` introducing new regressions while fixing | After max iterations, override with reason and open a follow-up backlog card |
+| 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) |
 
 ---

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

@@ -196,6 +196,80 @@ enhanced target). Mixing tiers within the same view is allowed only when the
 information density genuinely demands it (e.g. compact data table inside a
 cozy app shell) — document the exception in the registry.
 
+## Design Quality Rubric
+
+This is the SSOT for **intrinsic design quality** — the dimensions, weights, and
+severity mapping a critic uses to judge whether a rendered screen is *good
+design*, independent of whether it matches a mockup. The
+`ui-quality-critic` agent consumes this section (it cites these dimensions and
+grounds every numeric threshold in the Reference Tables above); the
+`/e2e-review` skill gates on the critic's output.
+
+This complements — does not replace — the fidelity check
+(`visual-fidelity-verifier`, "does the render match the mockup?"). Fidelity asks
+*conformance*; this rubric asks *quality*. A render can be pixel-faithful to a
+mediocre mockup, or have no mockup at all, and still be poor design — this rubric
+is what catches that.
+
+### Gating
+
+The rubric is **not** gated on `features.has_design_system`. Quality is judged on
+every UI surface: when a registry exists, the critic grounds numeric thresholds
+in the project's `tokens-reference.md`; when it does not, it grounds them in the
+Reference Tables above + `${paths.ui_guidelines}`. The wiring gate is
+`features.has_e2e_review` (the critic exists to serve `/e2e-review`).
+
+### The 10 dimensions + weights
+
+Each dimension is scored 0.0–1.0 (1.0 = no issue). The weighted mean is the
+`quality_score`. Weights bias toward dimensions that most determine whether a
+screen *works* over pure taste.
+
+| # | Dimension | Weight | Judges | Reference table |
+|---|---|---|---|---|
+| 1 | Visual hierarchy & focal clarity | 0.15 | One clear focal point; importance encoded by size/weight/color/space | Type scale |
+| 2 | Typographic rhythm | 0.12 | Sizes on one scale, ≤6–9 steps, paired line-height | Type scale |
+| 3 | Spacing rhythm & alignment | 0.12 | One spacing scale, consistent gaps, shared alignment edges | Spacing scale |
+| 4 | Color & contrast harmony | 0.12 | Disciplined, semantic palette; text meets contrast targets | Color contrast targets |
+| 5 | Density consistency | 0.08 | One density tier coherent with the audience | Density tiers |
+| 6 | Composition & balance | 0.10 | Negative space, Gestalt grouping, balanced visual weight | — |
+| 7 | State & affordance completeness | 0.13 | Idle/loading/empty/error/focus present; affordances read as interactive | — |
+| 8 | Motion quality | 0.05 | Purposeful, within duration budgets, reduced-motion aware | (motion-design skill) |
+| 9 | Polish & AI-generic smell | 0.08 | Intentional/branded; no default-template tells | — |
+| 10 | Aesthetic coherence with brand | 0.05 | Matches `identity.design_philosophy` / `${paths.ui_guidelines}` | — |
+
+Weights sum to 1.00. Dimensions not observable from the screenshot (e.g. motion
+on a static capture) are dropped and the remaining weights renormalized.
+
+### Dimension → severity mapping
+
+The critic maps each finding onto the **canonical severity taxonomy** defined in
+`framework/.claude/agents/visual-fidelity-verifier.md` § "Severity Taxonomy" (so
+fidelity and quality findings flow through one `/e2e-review` gate). The
+rule of thumb:
+
+- **Critical** — the dimension failure breaks the task: hierarchy so flat the
+  primary action is unclear, a primary action invisible/unreachable, body text
+  effectively unreadable (below the § Color contrast targets floor), a layout
+  that reads as broken.
+- **Major** — visible rhythm/quality break that a competent designer would
+  reject: off-scale type or spacing, clashing or meaningless color, mixed
+  density on a touch surface, missing empty/error/focus treatment, generic-AI
+  composition undercutting the brand.
+- **Minor** — small imperfection: 1–2px alignment drift, mild polish gap,
+  borderline density, motion nitpick.
+
+When a quality finding also bypasses a token, set `ds_drift_code:
+DS_TOKENS_DRIFT` so the orchestrator's drift summary stays unified.
+
+### Calibration discipline (why this beats a single "looks good?" prompt)
+
+Judging each dimension separately against explicit *excellent vs poor* anchors —
+rather than asking one holistic "is this good?" — is what makes the critique
+reproducible and actionable. The per-dimension anchors live in the
+`ui-quality-critic` agent body; this section owns the dimension list, the
+weights, and the severity mapping so they cannot drift across consumers.
+
 ## Token Cascade: primitive → semantic → component
 
 A mature token system has **three layers**, and components consume only the
@@ -431,6 +505,8 @@ The following files reference this module instead of duplicating its rules:
 
 - `framework/.claude/agents/ui-expert.md`
 - `framework/.claude/agents/code-reviewer.md`
+- `framework/.claude/agents/ui-quality-critic.md` (Design Quality Rubric — the
+  intrinsic-quality critic consumed by `/e2e-review` Phase 4b)
 - `framework/.claude/skills/ui-design/SKILL.md`
 - `framework/.claude/skills/frontend-design/SKILL.md`
 - `framework/.claude/skills/design-system-init/SKILL.md`

package/package.json

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