baldart 4.59.0 → 4.61.0

package/CHANGELOG.md

@@ -5,7 +5,24 @@ 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.59.0] - 2026-06-21
+## [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).
 
@@ -21,7 +38,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`framework/.claude/workflows/new-card-review.js`** (+ the final-review Fix phase) — collision-safe `finding_id` reconciliation. A writer that echoes only the human-readable id tail no longer drops applied fixes into residual (the empty-coder re-spawn bug): `resolveId` maps a returned token to its canonical prefixed id by exact or UNIQUE colon-tail match, logging any unmatched. Also a light-tier test gate: after the Fix phase at light tier (where qa-sentinel was skipped), a diff-scoped qa-sentinel pass now catches a fix-introduced test regression via the existing gateTable gate (graceful SKIP when no diff-scoped runner).
 - **`framework/.claude/skills/new/` references** — autonomous gate coverage + turn economy. Every `AskUserQuestion`/HALT gate across SKILL.md + `implement.md`, `setup.md`, `review-cycle.md`, `team-mode.md`, `completeness.md`, `merge-cleanup.md`, `commit.md`, `codex-gate.md`, `final-review.md`, `production-readiness.md` cites the AUTONOMOUS rule (so none silently blocks under `-auto` and none auto-approves a deferral); a sequential-path coverage assertion (review-cycle.md) catches a silently-skipped test-only card review; one concrete batching example added to the turn-economy HARD RULE.
 
-**MINOR** — additive: two new flags (`-auto`/`-auto-ship`) + an opt-in workflow Fix phase + one new `baldart.config.yml` key (`git.auto_deploy`, schema-change propagation applied) + reference-prose gate coverage. No new agent/skill/command/routine; no install/layout change. With the flags/args absent and `applyFixes` not opted in, every path is byte-identical to v4.58.0 (`new2` unaffected).
+**MINOR** — additive: two new flags (`-auto`/`-auto-ship`) + an opt-in workflow Fix phase + one new `baldart.config.yml` key (`git.auto_deploy`, schema-change propagation applied) + reference-prose gate coverage. No new agent/skill/command/routine; no install/layout change. With the flags/args absent and `applyFixes` not opted in, every path is byte-identical to v4.59.0 (`new2` unaffected).
+
+## [4.59.0] - 2026-06-20
+
+**Subagent return contracts — every orchestrator-facing agent now bounds its *final message* so a long body doesn't flood the spawning context.** Outcome of studying the [headroom](https://github.com/chopratejas/headroom) context-compression tool against BALDART's existing context-economy stack. The study's verdict: headroom is **not** adopted as a dependency — it is a heavyweight Python+Rust runtime (proxy/wrapper) that contradicts BALDART's "thin CLI + authored markdown, zero runtime" identity, is explicitly unsuitable for the ephemeral cloud sandboxes these sessions run in, and applies *lossy* compression to code/tool output (risky in a code-gen framework). Its techniques already have prompt-level analogues here: verbosity steering L0–L4 ≈ the Terse / Terse Ultra output styles, effort routing ≈ `effort-protocol`, AST/code compression ≈ the LSP + Graphify retrieval layers (which filter input *losslessly*).
+
+The one real gap headroom surfaced is the **verbosity of subagent return messages**: when free-form analysts (`codebase-architect`, `doc-reviewer`, `plan-auditor`, `senior-researcher`) finish, their entire reasoning body lands verbatim in the orchestrator's context — and the orchestrator pays for it on *every* subsequent turn of a batch. A subagent's final message is the only text that costs the spawning context tokens (its intermediate reading/thinking is discarded), so the whole optimization reduces to one rule: **persist the long form, return the short form.** This is implemented natively — zero dependencies, portable across Claude + Codex, works inside sandboxes — as the input-side twin of the effort protocol: effort governs how *deeply* an agent reasons, the return contract governs how *compactly* it reports back.
+
+The contract: COMPACT (default) = bounded headline/verdict + key points as `path:line` references (no reasoning dump, no pasted code) + `Report: <path>` when the long form is on disk; FULL narrative only when the user invoked the agent directly for prose. It reuses the existing pooled YAML findings schema (never a new one) and explicitly does **not** truncate substance — it cuts ceremony/narration/echo, not real findings. Agents already structured this way (`qa-sentinel` Return Protocol, `visual-fidelity-verifier` JSON, the verdict+pooled-YAML reviewers `code-reviewer` / `security-reviewer` / `api-perf-cost-auditor`) are the reference exemplars and were left untouched.
+
+**MINOR** — adds a protocol module + a template snippet (additive capability); no new `baldart.config.yml` key, so the schema-change propagation rule does not apply (same class as `effort-protocol`). No install/layout change.
+
+### Added
+
+- **`framework/agents/return-contract-protocol.md`** — new SSOT protocol module: COMPACT vs FULL return modes, the persist-then-summarize rule, findings-schema reuse, honest limits, and the canonical `## Return Contract` body block. Modeled on `effort-protocol.md`.
+- **`framework/templates/agent-return-contract.snippet.md`** — copy-paste starter for the `## Return Contract` block (twin of `skill-effort.snippet.md`), with placement guidance and the "skip agents already structured" carve-out.
+
+### Changed
+
+- **`framework/.claude/agents/{codebase-architect,doc-reviewer,plan-auditor,senior-researcher}.md`** — added an explicit `## Return Contract` block (tailored per agent: architect → file/symbol/pattern/risk map as `path:line`; doc-reviewer → condensed verdict + docs on disk; plan-auditor → verdict + pooled YAML, 10-section narrative is FULL-only; senior-researcher → §0–§11 report written to disk, return the Executive Summary + pointer).
+- **`framework/agents/index.md`** — added the return-contract routing rule and a Modules-list entry.
+- **`framework/.claude/agents/REGISTRY.md`** — added the return-contract convention note (exemplars + "paste the block for new analysis/audit/research agents").
 
 ## [4.58.0] - 2026-06-20
 

package/README.md

@@ -82,10 +82,10 @@ No additional activation steps needed — once installed, Claude Code (and Codex
 ### Core Protocol
 
 - **AGENTS.md**: Mandatory coordination rules (MUST/SHOULD/OPTIONAL)
-- **agents/**: 24 domain modules (architecture, workflows, testing, security, card-schema, i18n-protocol, etc.)
+- **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.59.0
+4.61.0

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

@@ -6,6 +6,8 @@ Quick-reference for all custom agents. Use this to route tasks to the right spec
 
 > **Machine-readable source of truth (since v3.20.0)**: the filesystem directory `framework/.claude/agents/` is authoritative for the list of BALDART agents. The `agent-discovery-gate.js` PreToolUse hook, the `agent-discovery-info.sh` SessionStart hook, and `baldart doctor` enumerate the directory directly (every `<name>.md` except this file is an agent — no manifest JSON is shipped). Adding a new agent means dropping `<name>.md` here; no other touchpoint.
 
+> **Return contract (since v4.59.0)**: every orchestrator-facing subagent bounds its **final message** so a long body doesn't flood the spawning context — COMPACT return (headline/verdict + `path:line` findings + disk pointer), long form persisted to disk. Agents already structured this way are the exemplars (`qa-sentinel` Return Protocol, `visual-fidelity-verifier` JSON, the verdict+pooled-YAML reviewers — `code-reviewer` / `security-reviewer` / `api-perf-cost-auditor`); free-form analysts carry an explicit `## Return Contract` block (`codebase-architect`, `doc-reviewer`, `plan-auditor`, `senior-researcher`). When adding a new analysis/audit/research agent, paste the block from `framework/templates/agent-return-contract.snippet.md`. Protocol: `framework/agents/return-contract-protocol.md`.
+
 ## Agent Map
 
 | Agent | Category | When to Use | Specialization | Can Edit Code | Key Tools |
@@ -23,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/codebase-architect.md

@@ -27,6 +27,15 @@ Per the project's AGENTS.md MUST rules, all agents must invoke you (codebase-arc
 
 4. **Pattern Recognition**: Identify and explain established patterns in the codebase, including coding standards, architectural decisions (from ADRs), and implementation conventions.
 
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message to the orchestrator is bounded —
+a structured file / symbol / pattern / risk map as `path:line` references, NOT a
+narrative essay. Lead with the headline answer; cite locations, don't paste code
+or restate what you read. Return only what the spawning agent needs to plan. FULL
+prose only when the user invoked you directly for an explanation. Mode definitions
+and the persist-then-summarize rule: `framework/agents/return-contract-protocol.md`.
+
 **Project-Specific Context:**
 
 This codebase follows strict protocols defined in AGENTS.md. Key architectural references you should consult:

package/framework/.claude/agents/doc-reviewer.md

@@ -36,6 +36,17 @@ Notes: [one-liner if any]
 
 For cards exceeding 3 files or triggering invariants, use the full Required Deliverables format (sections A-H, summarized under "Required Deliverables" below). If `.claude/skills/doc-reviewer-support/references/deliverables-format.md` exists, read it for the detailed section spec; otherwise use the inline summary.
 
+## Return Contract
+
+**Mode:** COMPACT (default). Your docs are written to disk; your final message to
+the orchestrator is bounded — the condensed verdict line (Verdict / invariants /
+docs written / SSOT updated) + violated rows + any `path:line` notes. Persist the
+long form (the docs themselves), return the short form. Never paste full doc bodies
+or the A–H narrative back into the orchestrator context. The Fast-Mode condensed
+format above IS the COMPACT return; use it as the ceiling even for larger cards
+(point to the docs on disk instead of inlining them). Mode definitions and the
+persist-then-summarize rule: `framework/agents/return-contract-protocol.md`.
+
 ## Parallel Safety (MUST)
 
 When running in parallel with other agents (code-reviewer, security-reviewer):

package/framework/.claude/agents/plan-auditor.md

@@ -22,6 +22,17 @@ You receive an existing implementation plan (created by another agent, a human,
 
 You review ANY development plan: frontend, backend, mobile, infra, data pipelines, AI/ML, integrations. Assume the plan may be incomplete or optimistic. You must expose gaps.
 
+## Return Contract
+
+**Mode:** COMPACT (default, orchestrator-spawned). Your final message is bounded —
+verdict line + the pooled YAML findings (the FINDINGS YAML SCHEMA below) + a
+`path:line`-referenced one-liner per BLOCKER. The 10-section narrative (OUTPUT
+FORMAT — FULL mode only) is **FULL mode**: emit it only when invoked directly by a
+human for an interactive audit, and when it is large, persist it and return the
+pointer. Don't paste the 10 sections back to an orchestrator that only needs the
+findings. Mode definitions, findings-schema reuse, and persist-then-summarize:
+`framework/agents/return-contract-protocol.md`.
+
 ## AUDIT MODE (read your invocation prompt FIRST)
 
 You operate in one of two declared modes. Detect which from your invocation prompt:

package/framework/.claude/agents/senior-researcher.md

@@ -35,6 +35,16 @@ The report will be read by an AI model with finite context. Therefore:
 - Use consistent terminology and define aliases once (glossary).
 - Use citation-friendly formatting: `[Author Year]` consistently throughout.
 
+## Return Contract
+
+**Mode:** COMPACT return, FULL deliverable-on-disk. The §0–§11 report below is your
+deliverable — **write it to disk** (a research file under the project's docs/wiki
+path). Your final message to the orchestrator is bounded: the Executive Summary
+headline + the recommendation line + `Report: <path>`. Do NOT paste the full
+§0–§11 body back into the orchestrator context — that is exactly the "finite
+context" cost the CRITICAL CONSTRAINT above warns about. Persist the long form,
+return the short form: `framework/agents/return-contract-protocol.md`.
+
 ## OUTPUT (DELIVERABLE)
 A detailed research report containing these sections in order:
 

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/framework/agents/index.md

@@ -36,6 +36,7 @@ Route agents to the right module with minimal reading.
 - If touching performance limits or scaling -> read `agents/performance.md`.
 - If touching monitoring/logging -> read `agents/observability.md`.
 - If tuning reasoning depth — setting a skill's `effort:` baseline or honoring an inline `effort=<level>` override -> read `agents/effort-protocol.md`.
+- If authoring/auditing a subagent whose return would flood the orchestrator context (free-form analysis/audit/research) -> read `agents/return-contract-protocol.md` and bound its final message: COMPACT headline + `path:line` findings + disk pointer, persist the long form. The input-side twin of the effort protocol.
 - If building or maintaining a derived LLM wiki overlay (`${paths.wiki_dir}/`) -> read `agents/llm-wiki-methodology.md` and invoke `wiki-curator` / `/capture`.
 - For day-to-day status -> read and update `${paths.references_dir}/project-status.md`.
 - For legacy context -> read `archive/project_full_legacy.md` if it exists.
@@ -71,6 +72,7 @@ When adding or updating agents, update REGISTRY.md — not this file.
 - `agents/i18n-protocol.md` — Internationalization discipline: no hardcoded user-facing strings, context registry (`paths.i18n_registry`) + ICU + context-aware translation; BLOCKING anti-hardcoded lint gate (since v4.52.0, gated on `features.has_i18n`)
 - `agents/design-system-protocol.md` — Registry-first discipline for UI work: BLOCKING cascade on `INDEX.md` + `tokens-reference.md` + `components/<Name>.md` (since v3.11.0, gated on `features.has_design_system`)
 - `agents/card-schema.md` — Atomic Card Baseline Schema: the universal, profile-aware (epic/child/standalone) field contract every backlog card satisfies, plus the consumer HALT/BACK-FILL/WARN contract (since v4.35.0)
+- `agents/return-contract-protocol.md` — Subagent return-message economy: COMPACT (bounded headline + `path:line` findings + disk pointer) vs FULL, persist-then-summarize — the input-side twin of `effort-protocol.md` (since v4.59.0)
 
 ## Where to Document (Decision Tree)
 

package/framework/agents/return-contract-protocol.md

@@ -0,0 +1,130 @@
+<!-- contamination-scan: skip
+     The only token the scanner flags here is the substring "fidelity" inside the
+     framework agent name `visual-fidelity-verifier` (a real BALDART agent cited as
+     a return-shape exemplar). It is framework content, not consumer project-leak. -->
+# Return Contract Protocol
+
+## Purpose
+
+Define how a BALDART **subagent** shapes the *final message* it returns to the
+orchestrator that spawned it. The goal is **context economy of the orchestrator**:
+a subagent's full reasoning is often large (analysis, audits, research, doc
+sweeps), and when that whole body lands verbatim in the orchestrator's context it
+crowds out everything else and inflates token cost for every subsequent turn. The
+contract is simple — **persist the long form, return the short form**: the
+deliverable lives on disk (or as structured findings), and the message back to the
+orchestrator is a bounded headline + pointers, never a reasoning dump.
+
+This is the input-side twin of the `effort-protocol`: effort governs how *deeply*
+an agent reasons; this governs how *compactly* it reports back.
+
+## Scope
+
+**In**: The shape and size ceiling of a subagent's *return message* (its last
+action before yielding to the orchestrator), the COMPACT vs FULL distinction, and
+where the long-form body goes instead.
+**Out**: What an agent writes to disk (that is the agent's own deliverable format —
+docs, reports, locale files, cards), the native effort knob (see
+`effort-protocol.md`), and runtime/wire-level token compression (BALDART does not
+ship a runtime; this is a prompt-level authoring convention, not a proxy).
+
+## Background — why the return message is the lever
+
+A subagent invoked via the `Task` tool runs in its own context window; only its
+**final message** is injected back into the orchestrator's context. So the only
+text that costs the orchestrator tokens is that final message — not the agent's
+intermediate reading, thinking, or tool calls. Therefore the entire optimization
+reduces to one rule: **make the final message bounded and structured.** Everything
+the agent needed to reason over stays in its own (discarded) context; the
+durable long-form output, when it is a deliverable, goes to disk where the
+orchestrator can read it on demand instead of paying for it on every turn.
+
+## The two modes
+
+### COMPACT (default for every orchestrator-facing subagent)
+
+The final message is bounded and consists only of:
+
+1. **Headline / verdict** — one line: the outcome (`PASS | FAIL`, "analysis
+   ready", "3 findings", "report written").
+2. **Findings or key points** — as `path:line` references, not pasted code or
+   prose. If the agent emits review findings, use the shared pooled YAML findings
+   schema (see "Reuse the existing findings schema" below) — do not invent a new
+   one.
+3. **Disk pointer** — `Report: <path>` (or `Doc: <path>`, `Cards: <path>`) when
+   the full analysis was persisted, so the orchestrator can read the long form
+   only if it needs to.
+
+Keep it tight — model the ceiling on `qa-sentinel`'s "Return Protocol" (a short
+final message, *not* the full report) and `visual-fidelity-verifier`'s strict
+JSON. A good COMPACT return is tens of lines, not hundreds. **No preamble, no
+restating the task, no narrating what you read.**
+
+### FULL (opt-in, narrow)
+
+The agent returns extended narrative **only** when:
+- the agent was invoked **directly by the user** (not by an orchestrator) for an
+  explanation/exploration where the prose *is* the answer; or
+- the agent's deliverable is inherently the long-form text AND there is no disk to
+  persist it to.
+
+Even in FULL mode, prefer **persist-then-summarize**: if the agent can write the
+long form to disk (a report, a doc, a research file), do that and return COMPACT
+with the pointer. FULL is the exception, not the fallback.
+
+## Persist-then-summarize (the guiding rule)
+
+If your reasoning is a deliverable, **write it to disk and return the pointer.**
+The orchestrator's context is not an archive — it is a working set. An agent that
+writes its report to `/qa/<CARD-ID>.md`, `${paths.references_dir}/...`, or a
+research file and returns a three-line pointer has done its job better than one
+that pastes 800 lines back, because the orchestrator pays for those 800 lines on
+*every* subsequent turn of the batch.
+
+## Reuse the existing findings schema
+
+Review/audit agents that emit findings already share one pooled YAML schema
+(`finding_id / title / source / category / severity / confidence /
+evidence{file,lines,quote ≤8} / minimal_fix_direction / …`), parsed by
+`/codexreview` and the `/new` review fan-in. The COMPACT return **reuses that
+schema** — it is already terse and machine-readable. Never define a per-agent
+findings shape.
+
+## Honest limits
+
+This is a **prompt-level authoring convention**, best-effort — not a parser that
+truncates output. It works because the agent follows its own contract, exactly
+like the thinking-keyword escalation in `effort-protocol.md`. Two consequences:
+
+1. **Don't drop signal to hit a line count.** COMPACT means *no ceremony and no
+   dumps*, not lossy omission of a real BLOCKER. If the findings genuinely need 60
+   lines, use 60 — the win is cutting preamble/narration/echo, not truncating
+   substance. (This mirrors headroom's verbosity L1–L3: remove ceremony and echo
+   first; "caveman" L4 fragmentation is for prose, never for findings.)
+2. **Agents already structured stay as they are.** `qa-sentinel` (Return
+   Protocol), `visual-fidelity-verifier` (JSON schema), `code-reviewer` /
+   `security-reviewer` / `api-perf-cost-auditor` (verdict line + pooled YAML
+   findings, capped narrative) already satisfy this contract — they are the
+   reference exemplars, not edit targets.
+
+## The canonical body block
+
+Every orchestrator-facing subagent that returns free-form analysis pastes a short
+`## Return Contract` section into its body (after `## Core Responsibilities` /
+`## Mission`, or after the role preamble). Keep it dense — cite this module, do
+not re-explain the modes:
+
+```markdown
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message to the orchestrator is bounded —
+headline/verdict + key points as `path:line` (no reasoning dump, no pasted code) +
+`Report: <path>` when the full analysis is on disk. Persist the long form, return
+the short form. FULL narrative only when the user invoked you directly for prose.
+Findings schema, mode definitions, and the persist-then-summarize rule:
+`framework/agents/return-contract-protocol.md`.
+```
+
+A copy-paste starter lives at `framework/templates/agent-return-contract.snippet.md`.
+When adding a new orchestrator-facing agent, paste this block — the convention is
+recorded in `framework/.claude/agents/REGISTRY.md` (the agent SSOT).

package/framework/templates/agent-return-contract.snippet.md

@@ -0,0 +1,30 @@
+<!-- contamination-scan: skip
+     The only token the scanner flags is "fidelity" inside the framework agent name
+     `visual-fidelity-verifier` (cited as an exemplar) — framework content, not leak. -->
+<!--
+  RETURN CONTRACT HEADER — paste this into any orchestrator-facing BALDART
+  subagent that would otherwise return free-form analysis/audit/research prose.
+
+  Paste the `## Return Contract` block below right after `## Core Responsibilities`
+  / `## Mission` (or after the role preamble). It bounds the agent's FINAL MESSAGE
+  to the orchestrator so a long body doesn't flood the orchestrator's context —
+  the long form goes to disk, the return is a short headline + pointers.
+
+  Skip for agents that ALREADY have a tight return shape (qa-sentinel's Return
+  Protocol, visual-fidelity-verifier's JSON, the verdict+pooled-YAML reviewers) —
+  they are the reference exemplars, not edit targets.
+
+  Full protocol: framework/agents/return-contract-protocol.md
+
+  Keep this header DENSE (4-5 lines). Do not re-explain the modes —
+  cite framework/agents/return-contract-protocol.md instead.
+-->
+
+## Return Contract
+
+**Mode:** COMPACT (default). Your final message to the orchestrator is bounded —
+headline/verdict + key points as `path:line` (no reasoning dump, no pasted code) +
+`Report: <path>` when the full analysis is on disk. Persist the long form, return
+the short form. FULL narrative only when the user invoked you directly for prose.
+Findings schema, mode definitions, and the persist-then-summarize rule:
+`framework/agents/return-contract-protocol.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.59.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"