baldart 4.70.0 → 4.71.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.71.0] - 2026-06-25
+
+**Responsive-awareness in UI review — catch a viewport-scoped edit that regresses the *other* viewport.** When an agent works on one viewport (fix the mobile header, tweak the desktop table), nothing today catches it silently shifting the viewport it was *not* editing. The obvious fix — cloning the i18n ESLint gate into a `responsive-gate` that bans raw `matchMedia`/breakpoint literals — was **refuted** by an adversarial pass: that gate is blind to where responsiveness actually lives (Tailwind `md:` classes, CSS, CSS-in-JS — not `window.matchMedia`), so it is mayo-specific opinion, not a distributable mechanism. The real driver is served by **reactivating machinery that already exists and was inert**: `visual-fidelity-verifier` has had a `responsiveness-break` finding all along, but `/e2e-review` only ever screenshotted **one** viewport (1440px), so it could never fire.
+
+**MINOR** — adds review capability; **no new config key** (rides on `features.has_e2e_review` + `features.has_design_system`), no schema-change propagation. The mobile viewport is fixed at 375px (the canonical small-screen audit width). Degrades to no-op on consumers without e2e-review. The per-route cost was **measured** on a real verifier run before shipping default-on: ~one extra verifier call per renderable route (~0.3% of a card run — the 375px screenshot is lighter than the 1440px one, and only renderable routes incur it).
+
+### Changed
+
+- **`/e2e-review` captures both viewports + runs a mobile responsive-integrity pass** (`framework/.claude/skills/e2e-review/SKILL.md`). Phase 3 now captures `<route-slug>.png` (desktop 1440×900, **unchanged path** — all existing consumers intact) AND `<route-slug>@mobile.png` (375×812), setting the viewport before navigating so SSR/responsive hooks render for that width. Phase 4 adds a second verifier invocation per route with `viewport_role: "mobile"` (step 2b), and the `skip`-level pre-filter no longer suppresses it (the mobile pass needs no mockup). Findings aggregate with `viewport_role` in the dedup key so a mobile `responsiveness-break` stays distinct and the Phase 5 gate / self-heal report show which viewport broke.
+- **`visual-fidelity-verifier` gains a `viewport_role: "mobile"` responsive-integrity mode** (`framework/.claude/agents/visual-fidelity-verifier.md`). When set, it does NOT diff against the (desktop) mockup — the mobile layout reflows by design — and emits ONLY genuine breakage findings (`responsiveness-break`, `unreachable-action`, `layout-break`), conservatively. Reuses the existing taxonomy + output schema; no new finding codes.
+- **`design-system-protocol.md` adds a "Responsive Scope Discipline" section** — the textual SSOT: (1) a viewport-scoped edit MUST NOT alter the other viewport's branch; (2) a structural/heavy component MUST NOT be swapped across viewports via `display:none`/`visibility`/`hidden`/`@media` CSS hiding (mounts both branches, runs both effect/query sets, ships dead DOM). Stated abstractly — concrete primitive names / breakpoints / any project-local gate live in the consumer's own files, never in the framework. Enforced as a **review check** (the CSS-hidden case is invisible to a JS AST rule), not a lint.
+- **`code-reviewer` enforces it** (rule 9) — structural `display:none` swap = HIGH; viewport-scoped edit that mutates the other branch = MEDIUM. **`design-review.md`** checklist points to the same section. This is the surviving, generalized slice of the responsive work; everything stack-specific (a project's `eslint.responsive.config.mjs`, primitive names) stays a consumer-side project file, never in `.framework/`.
+
 ## [4.70.0] - 2026-06-25
 
 **`/ds-edit` — the deliberate-edit twin of `/ds-new`, completing the single-element lifecycle.** `/ds-new` creates (its reuse-first step STOPS if the element exists); there was no symmetric guided entry to *change* an existing canonical element. "Update a component" decomposes into three cases — two were already covered: the **mechanical doc-resync** after a code change is automatic (serializer regenerates the HEAD from source, preserving agentic + prose; the BLOCKING `DS_COMPONENT_STALE` gate enforces it), and **agentic re-curation** is `doc-reviewer`'s domain. The gap was the **deliberate change with a decision** — add a variant/prop, a breaking change, or re-governing a closed-set role.

package/VERSION

@@ -1 +1 @@
-4.70.0
+4.71.0

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

@@ -115,6 +115,15 @@ Concrete enforcement contract for the review pass:
    HEAD is NOT `DS_COMPONENT_STALE` merely for that; empty deterministic HEAD
    fields (non-TS stack, unresolved prop) are advisory, never blocking. The HEAD
    is an upgrade target — see `component-manifest-schema.md` § Transition leniency.
+9. **Responsive Scope Discipline** — per [`design-system-protocol.md`](../../agents/design-system-protocol.md)
+   § "Responsive Scope Discipline": (a) a structural/heavy component swapped
+   across viewports via `display:none` / `visibility:hidden` / `hidden` / `@media`
+   CSS hiding (mounts both branches, runs both effect/query sets, ships dead DOM)
+   is **HIGH**; (b) a viewport-scoped edit that also mutates the *other* viewport's
+   branch (e.g. a "mobile only" change that shifts the desktop layout) is
+   **MEDIUM**. Token-level per-breakpoint restyling of a single element is fine —
+   only whole-tree `display:none` swaps trip (a). This is a review judgement, not a
+   lint (the CSS-hidden case is invisible to a JS AST rule).
 
 When `features.has_design_system: false`, the registry reads are skipped but
 the review still flags hardcoded values and inconsistencies against

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

@@ -63,6 +63,7 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
   "card_id": "FEAT-XXXX",
   "route": "/dashboard",
   "viewport": { "width": 1440, "height": 900 },
+  "viewport_role": "desktop" | "mobile",          // optional, default "desktop"
   "implementation_screenshot_path": "/abs/path/to/impl.png",
   "mockup_source": {
     "level": "figma" | "local" | "compliance-only" | "skip",
@@ -81,7 +82,22 @@ The orchestrator (`/e2e-review`) invokes you with this JSON payload:
 ```
 
 If `mockup_source.level == "skip"`, return immediately with
-`{ "status": "skipped", "reason": "no_mockup_available", "findings": [] }`.
+`{ "status": "skipped", "reason": "no_mockup_available", "findings": [] }` —
+**unless** `viewport_role == "mobile"`, in which case run the responsive-integrity
+pass below (it needs no mockup).
+
+**`viewport_role: "mobile"` — responsive-integrity pass.** When set, you are
+looking at the **mobile render** (a narrow viewport, typically 375px). Mobile
+mockups are rarely provided, and the mobile layout *correctly* reflows away from
+any desktop mockup — so in this mode you **do NOT diff against a mockup** and you
+do **NOT** emit fidelity findings (`element-order`, `spacing-off-scale`,
+`typography-*`, `color-*` relative to a desktop design). Evaluate the mobile
+screenshot on its own and flag **only genuine viewport breakage**:
+`responsiveness-break` (horizontal scroll past the viewport, content cut off,
+elements overlapping/unreadable), `unreachable-action` (primary CTA off-screen or
+behind a fixed overlay), and `layout-break` (a container that genuinely collapsed,
+not an intended stack). Be conservative: a dense-but-legible layout is **not** a
+break — flag only hard failures a user would hit. Return the same output schema.
 
 **`resolved_orphans` carve-out (Functional Traceability Gate).** The mockup is a
 fidelity target, not a requirements oracle: it may contain interactive chrome that

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

@@ -273,14 +273,27 @@ capture the result + screenshots per route.
    - Use `page.getByRole()`, `page.getByText()`, `page.getByTestId()` —
      never CSS selectors that depend on Tailwind class strings.
    - Use `expect(locator)` with auto-waiting.
-   - For each route in the scenario, call:
+   - For each route in the scenario, capture BOTH viewports (set the viewport
+     BEFORE navigating so SSR / responsive hooks render for that width):
+       // Desktop — existing path, consumed by Phase 4 / 4b. DO NOT change it.
+       await page.setViewportSize({ width: 1440, height: 900 });
        await page.goto(route);
        await page.waitForLoadState("networkidle");
        await page.screenshot({
          path: ".baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>.png",
          fullPage: true
        });
-     The screenshot path is consumed by the visual-fidelity-verifier in Phase 4 — do not change it.
+       // Mobile — additive, enables the responsiveness-break check (Phase 4).
+       await page.setViewportSize({ width: 375, height: 812 });
+       await page.goto(route);
+       await page.waitForLoadState("networkidle");
+       await page.screenshot({
+         path: ".baldart/e2e-review/<CARD-ID>/screenshots/<route-slug>@mobile.png",
+         fullPage: true
+       });
+     Both screenshot paths are consumed by the visual-fidelity-verifier in
+     Phase 4 — do not change them. 375px is the canonical small-screen audit
+     width (design-system-protocol Reference Tables); it is fixed, not a config key.
    - For OTP-driven personas (test_plan.test_credentials.auth_method == "otp"),
      use `await page.pause()` between phone-entry and code-entry. Document
      the manual step in a test.step block.
@@ -309,7 +322,8 @@ capture the result + screenshots per route.
    - `status`: `passed` | `failed` | `flaky` | `skipped`
    - `duration_ms`
    - `failure_reason` (when failed, the first assertion error + stack hint)
-   - `screenshot_paths[]` (one per route in the scenario)
+   - `screenshot_paths[]` (per route: the desktop `<route-slug>.png` AND the
+     mobile `<route-slug>@mobile.png`)
 5. **Functional findings**: every `failed` or `flaky` scenario becomes a
    functional finding in the aggregate report (Phase 5). Severity:
    - Auth / payments / data-mutation scenario failed → `critical`
@@ -336,7 +350,11 @@ For each `route` in `plan.routes[]`:
      latency / cost saver — most routes pass pixel diff cleanly.
    - When `mockup_source.level == "compliance-only"`, skip pre-filter (no
      image to compare against) and proceed directly to step 2.
-   - When `mockup_source.level == "skip"`, skip this route entirely.
+   - When `mockup_source.level == "skip"`, skip the **desktop fidelity diff**
+     (steps 2) for this route — but still run the **mobile responsive pass**
+     (step 2b) if a `<route-slug>@mobile.png` screenshot was captured, since it
+     needs no mockup. Skip the route entirely only when no screenshot exists
+     (route unrenderable).
 2. **Invoke `visual-fidelity-verifier`** with the input contract documented
    in [`visual-fidelity-verifier.md`](../../agents/visual-fidelity-verifier.md):
 
@@ -365,12 +383,46 @@ For each `route` in `plan.routes[]`:
    verifier from flagging a deliberately-removed orphan affordance as
    `component-missing`. Omit the field (or pass `[]`) when the inventory has no
    resolved orphans.
+2b. **Mobile responsive-integrity pass.** Invoke the verifier a **second** time
+   for the same route with the mobile screenshot, so its `responsiveness-break`
+   check (which never fires on a desktop-only screenshot) can run. This is what
+   catches a viewport-scoped edit that regresses the *other* viewport:
+
+   ```
+   subagent_type: "visual-fidelity-verifier"
+   prompt: |
+     Compare the implementation against the mockup and return JSON per your
+     output schema.
+
+     Input payload:
+     {
+       "card_id": "FEAT-XXXX",
+       "route": "/dashboard",
+       "viewport": { "width": 375, "height": 812 },
+       "viewport_role": "mobile",
+       "implementation_screenshot_path": ".baldart/e2e-review/FEAT-XXXX/screenshots/<route-slug>@mobile.png",
+       "mockup_source": { "level": "skip" },
+       "tolerance": "<from config>"
+     }
+   ```
+   `viewport_role: "mobile"` puts the verifier in responsive-integrity mode: it
+   does NOT diff against the desktop mockup (the mobile layout reflows by design)
+   and emits ONLY genuine breakage findings (`responsiveness-break`,
+   `unreachable-action`, `layout-break`). Run this pass on every renderable route
+   (a desktop screenshot exists); skip it only when the route is explicitly marked
+   desktop-only in the plan. Cost is ~one extra verifier call per route — measured
+   marginal (~0.3% of a card run) because the 375px screenshot is lighter than the
+   1440px one and only renderable routes incur it.
 3. **Parse the agent's JSON response** strictly. If the response is malformed
    or contains prose outside the JSON, log
    `verifier_protocol_violation` in `gaps[]` and treat the route's findings
    as empty (do not invent findings from prose).
-4. **Aggregate** visual findings across all routes into a single
-   `visual_findings[]` array, deduplicating by `(route, category, region)`.
+4. **Aggregate** visual findings from BOTH passes across all routes into a single
+   `visual_findings[]` array, deduplicating by `(route, viewport_role, category,
+   region)` — `viewport_role` keeps a mobile `responsiveness-break` distinct from
+   any desktop finding on the same route. Tag each mobile-pass finding with
+   `viewport_role: "mobile"` so the Phase 5 gate and self-heal report show which
+   viewport broke.
 
 ---
 

package/framework/agents/design-review.md

@@ -73,6 +73,9 @@ recommend `/design-system-init`.
 - [ ] No horizontal scroll on mobile
 - [ ] Touch targets minimum 44x44px
 - [ ] Content hierarchy clear
+- [ ] Responsive Scope Discipline (design-system-protocol.md § "Responsive Scope
+      Discipline"): no structural component swapped via `display:none`; a
+      viewport-scoped change does not regress the other viewport
 
 ### Interaction Design
 

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

@@ -545,6 +545,37 @@ implemented (or is about to be) without a traceable function. HIGH severity:
 it ships dead code and erodes the minimalism contract. The fix is always one of
 the three outcomes above, never "leave it, it matches the mockup".
 
+## Responsive Scope Discipline
+
+A UI surface usually renders across viewports (mobile / tablet / desktop). Two
+rules keep responsive work from regressing the viewport you are *not* editing —
+the framework states them abstractly; the concrete primitive names, breakpoint
+values and any project-specific gate live in the consumer's own files (CLAUDE.md,
+overlays, a project-local linter), never here.
+
+1. **Viewport-scoped edits stay scoped.** When a change targets one viewport
+   (e.g. "fix the mobile header"), it MUST NOT alter the other viewport's branch.
+   Editing the mobile path and silently shifting the desktop layout — or vice
+   versa — is a regression even when the targeted viewport looks correct. Verify
+   both viewports before declaring the task done (`/e2e-review` renders at 1440px
+   and 375px and runs the `responsiveness-break` check at each).
+
+2. **No structural component swapped via `display:none`.** A DOM-structural or
+   heavy component (one that mounts a non-trivial subtree, fetches data, or has
+   expensive children) MUST NOT be shown/hidden across viewports via
+   `display:none` / `visibility:hidden` / a `hidden` attribute / `@media` CSS
+   hiding. Mounting both branches and hiding one ships dead DOM, runs *both*
+   components' effects and queries, and doubles the work on every render. Render
+   only the active branch (a viewport hook / conditional render) instead.
+   Token-level responsive styling — a single element restyled per breakpoint
+   (padding, font-size, direction) — is fine; it is *swapping whole component
+   trees* via `display:none` that this rule rejects.
+
+Enforcement is a **review check** (`code-reviewer`, `/design-review`), not a lint:
+the most damaging case (a CSS-hidden heavy subtree) is invisible to a JS AST rule.
+Rule 2 violations are HIGH; a viewport-scoped edit that mutates the other branch
+(rule 1) is MEDIUM.
+
 ## Post-Intervention Coherence Check (BLOCKING completion gate)
 
 The BLOCKING pre-work above enforces *reads* before any UI change. This

package/package.json

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