mandrel 2.50.0 → 2.51.0

package/.agents/audit-checklists/accessibility.md

@@ -12,6 +12,7 @@ Self-check your change against this lens's concerns before you ship:
 
 - [ ] `audit-accessibility` (this lens)
 - [ ] `audit-ux-ui`
+- [ ] `audit-mobile`
 - [ ] Renderable surface
 - [ ] Static a11y tooling already in the repo
 - [ ] Design tokens

package/.agents/audit-checklists/mobile.md

@@ -0,0 +1,35 @@
+<!-- GENERATED FILE — do not edit by hand.
+     Source of truth: .agents/workflows/audit-mobile.md
+     Regenerate: node .agents/scripts/generate-lens-checklists.js
+     Drift is gated by: npm run docs:check
+-->
+
+# Mobile & Tablet UX Audit — authoring checklist
+
+> Audit mobile and tablet UX — layout and viewport correctness, touch ergonomics, responsive assets, and whether anything actually verifies them at a small viewport (static-first, with an optional runtime viewport pass)
+
+Self-check your change against this lens's concerns before you ship:
+
+- [ ] Breakpoint scale
+- [ ] Viewport contract
+- [ ] Declared device matrix
+- [ ] Runtime target (optional)
+- [ ] Viewport meta
+- [ ] Fixed dimensions
+- [ ] Viewport-height units
+- [ ] Horizontal overflow
+- [ ] Safe-area insets
+- [ ] Hover-only interaction
+- [ ] Control size and spacing
+- [ ] Input ergonomics
+- [ ] Gesture conflicts
+- [ ] Images
+- [ ] Media and embeds
+- [ ] Typography and spacing
+- [ ] Coverage — is anything exercised at a non-desktop viewport?
+- [ ] Effectiveness — does that exercise assert anything mobile-specific?
+- [ ] Resolve the target from config — never a hardcoded URL.
+- [ ] Sample routes from the navigability SSOT.
+- [ ] Drive two form factors per route.
+- [ ] Median-of-3 or provisional.
+- [ ] Leave the viewport as you found it.

package/.agents/audit-checklists/ux-ui.md

@@ -21,5 +21,4 @@ Self-check your change against this lens's concerns before you ship:
 - [ ] Information Hierarchy
 - [ ] Error States
 - [ ] Loading States
-- [ ] Responsiveness
 - [ ] Accessibility (UX-focused)

package/.agents/docs/workflows.md

@@ -32,7 +32,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (28)
+## Commands (29)
 
 | Command | Description |
 | --- | --- |
@@ -45,6 +45,7 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |
 | `/audit-devops` | Audit CI/CD workflows, container images, infrastructure-as-code, and deployment pipelines; surface failure modes and hardening gaps. |
 | `/audit-documentation` | Audit the repository's main documentation for staleness, semantic drift, and completeness; emit a structured High/Medium/Low findings report. |
+| `/audit-mobile` | Audit mobile and tablet UX — layout and viewport correctness, touch ergonomics, responsive assets, and whether anything actually verifies them at a small viewport (static-first, with an optional runtime viewport pass) |
 | `/audit-navigability` | Audit the whole route tree against the consumer's nav-registry SSOT — every route has a persona nav door and no nav href is dead. A deliberately-global lens exempt from the cross-epic-leak guard and routed onto route-adding change sets. |
 | `/audit-performance` | Audit performance by measuring first — profile hot paths, I/O, memory, and payload against the repo's own numbers — and audit interleaving/partial-failure correctness (TOCTOU, unawaited promises, non-atomic writes) as a first-class dimension. |
 | `/audit-privacy` | Audit logs, telemetry, and persistence paths for PII leakage and retention violations; surface secrets exposure and consent gaps. |

package/.agents/schemas/audit-rules.json

@@ -299,6 +299,36 @@
       "scope": "local",
       "substitutionKeys": []
     },
+    "audit-mobile": {
+      "triggers": {
+        "gates": ["gate2", "gate3"],
+        "keywords": [
+          "mobile",
+          "tablet",
+          "responsive",
+          "breakpoint",
+          "viewport",
+          "touch"
+        ],
+        "filePatterns": [
+          "**/*.html",
+          "**/*.astro",
+          "**/*.css",
+          "**/*.{scss,sass,less}",
+          "**/styles/**",
+          "**/components/**/*.{js,jsx,ts,tsx,vue,svelte}",
+          "**/app/**/{page,layout,route,head,default,template,loading,error,not-found}.{js,jsx,ts,tsx}",
+          "**/pages/**/*.{js,jsx,ts,tsx,vue}",
+          "**/routes/**/*.{jsx,tsx,vue,svelte}",
+          "**/tailwind.config.{js,ts,cjs,mjs}",
+          "**/playwright.config.{js,ts,cjs,mjs}",
+          "**/cypress.config.{js,ts,cjs,mjs}"
+        ]
+      },
+      "target": "web",
+      "scope": "local",
+      "substitutionKeys": []
+    },
     "audit-navigability": {
       "triggers": {
         "gates": ["gate2", "gate3"],

package/.agents/scripts/lib/audit-to-stories/audit-lenses.js

@@ -33,6 +33,7 @@ export const AUDIT_LENSES = Object.freeze([
   'dependencies',
   'devops',
   'documentation',
+  'mobile',
   'navigability',
   'performance',
   'privacy',

package/.agents/workflows/audit-accessibility.md

@@ -31,9 +31,9 @@ on a project with no rendered frontend, since there are no components, templates
 or routes to hold to WCAG. See the `target` key's schema description for how
 applicability is probed from the consumer's checkout.
 
-## Boundary with `audit-ux-ui`
+## Boundaries with the neighbouring web lenses
 
-These two web lenses share a border and must not double-report:
+These lenses share a border with this one and must not double-report:
 
 - **`audit-accessibility` (this lens)** owns **WCAG conformance** — the
   standards question: does an assistive-technology user perceive, operate, and
@@ -41,11 +41,17 @@ These two web lenses share a border and must not double-report:
   controls, text alternatives, and contrast against the WCAG ratio thresholds.
 - **`audit-ux-ui`** owns **design-system adherence** — the consistency
   question: do components and tokens match the project's own design system?
-
-Contrast is the one axis both can touch: **accessibility owns the WCAG ratio
-verdict** (4.5:1 body / 3:1 large text / 3:1 non-text), while ux-ui owns whether
-the colour came from a sanctioned token. When a contrast defect is in scope for
-both, report the WCAG failure here and leave the token-adherence note to ux-ui.
+- **`audit-mobile`** owns **small-screen and touch behaviour** — layout at a
+  phone or tablet viewport, touch ergonomics, responsive assets, and mobile
+  test coverage. It may measure a control's rendered size as ergonomic
+  evidence, but the `2.5.8 Target Size (Minimum)` verdict on an undersized
+  target is reported here.
+
+Contrast is the one axis accessibility and ux-ui both touch: **accessibility
+owns the WCAG ratio verdict** (4.5:1 body / 3:1 large text / 3:1 non-text),
+while ux-ui owns whether the colour came from a sanctioned token. When a
+contrast defect is in scope for both, report the WCAG failure here and leave
+the token-adherence note to ux-ui.
 
 ## Scope
 

package/.agents/workflows/audit-mobile.md

@@ -0,0 +1,242 @@
+---
+description: Audit mobile and tablet UX — layout and viewport correctness, touch ergonomics, responsive assets, and whether anything actually verifies them at a small viewport (static-first, with an optional runtime viewport pass)
+---
+
+# Mobile & Tablet UX Audit
+
+You are a Senior Mobile Web Engineer holding the frontend to its **small-screen
+and touch contract**: does every surface lay out, scroll, and answer a finger on
+a phone and a tablet — and does anything in the suite actually verify that it
+does? Default to **static** detection over source; escalate to a **runtime**
+viewport pass only when a live target is configured. The shared lens machinery —
+read-only constraint, scope interpretation, report envelope + finding-block
+skeleton, severity scale, self-cross-check, and execution strategy — lives in
+[`helpers/audit-lens-core.md`](helpers/audit-lens-core.md). Write the report to
+`{{auditOutputDir}}/audit-mobile-results.md`. Dimension values:
+`Layout & Viewport | Touch Ergonomics | Responsive Assets | Mobile Verification`.
+Extra finding field: **Evidence:** (`measured | static` + the observable;
+single-run runtime numbers are tagged `provisional`).
+The report adds a **Runtime Viewport Pass** section.
+
+> **An emulated viewport is not a device.** Viewport emulation resizes and
+> re-flows the page; it does not reproduce a real device's browser engine,
+> input latency, font rendering, or OS chrome. Report what the emulator
+> observed, never "verified on iPhone".
+
+## Applicability
+
+**Web targets only.** Registered with `target: "web"` in
+[`audit-rules.json`](../schemas/audit-rules.json): the selector skips this lens
+on a project with no rendered frontend, since there is no layout to re-flow and
+no control to touch. See the `target` key's schema description for how
+applicability is probed from the consumer's checkout.
+
+## Boundaries with the neighbouring lenses
+
+Four lenses border this one. Report a finding **here** only when it is a
+small-screen or touch defect; defer the rest so the suite never double-reports:
+
+- [`/audit-accessibility`](audit-accessibility.md) owns every **WCAG
+  success-criterion verdict**, including `2.5.8 Target Size (Minimum)`. This
+  lens may **measure** a control's rendered size as ergonomic evidence, but the
+  conformance verdict on an undersized target belongs there.
+- [`/audit-ux-ui`](audit-ux-ui.md) owns **design-system adherence** — whether a
+  value came from a sanctioned token and whether a raw element should have
+  deferred to a design-system component. This lens asks only whether the result
+  works at a small viewport, whatever its provenance.
+- [`/audit-performance`](audit-performance.md) owns **Core Web Vitals, bundle
+  weight, and network cost**, mobile ones included. An oversized hero image is
+  reported here only as a missing `srcset`/`sizes` **contract**, never as a
+  payload-weight verdict.
+- [`/audit-quality`](audit-quality.md) owns the **generic** test verdicts —
+  pyramid balance, flake, and coverage gaps. This lens owns exactly one test
+  question: is any of it exercised at a non-desktop viewport, and does that
+  exercise assert something mobile-specific (Step 2).
+
+## Scope
+
+Interpret this lens's change-set fence per the core's Scope interpretation:
+
+```text
+{{changedFiles}}
+```
+
+## Execution strategy
+
+Run this lens as a single `subagent_type: auditor` dispatch returning the report
+path + Executive Summary; sequential inline execution is the fallback (see the
+core's Execution strategy).
+
+## Step 0: Discover the responsive baseline (run first)
+
+**You cannot audit responsiveness against a generic ideal — a 640px fixed width
+is a defect only relative to the breakpoints the project actually claims to
+support.** Before any detection, locate this lens's own sources of truth (they
+are *not* ux-ui's design system, though they often live beside it) and record
+what they declare:
+
+- **Breakpoint scale:** the `screens` map in `tailwind.config.{js,ts}`, CSS
+  custom media / container queries, a `breakpoints` token file, or a
+  CSS-in-JS theme's media helpers. Census the `@media` / `container` queries
+  actually used in the stylesheets and note the narrowest one — that is the
+  smallest width the project has any evidence of supporting.
+- **Viewport contract:** the `<meta name="viewport">` tag (or the framework
+  `viewport` export) and whether it sets `width=device-width` and leaves user
+  scaling enabled.
+- **Declared device matrix:** any non-desktop viewport already configured in the
+  consumer's test tooling — Playwright `projects[]` using `devices[...]` or an
+  explicit `viewport`, a Cypress `viewportWidth`/`viewportHeight`, a
+  visual-regression viewport list. This is the project's own statement of which
+  form factors it holds itself to.
+- **Runtime target (optional):** the `qa.environments` map (see
+  [*Runtime viewport pass*](#step-3-runtime-viewport-pass-optional-corroboration))
+  and the navigability route SSOT.
+
+Record the breakpoints, the viewport contract, and the device matrix. Every
+finding downstream is measured against *this discovered baseline*. If the
+project declares **no** breakpoint scale and no device matrix, say so and
+downgrade findings to "no responsive baseline declared — recommend establishing
+a breakpoint scale and a phone/tablet test viewport first" rather than scoring
+the tree against an invented one.
+
+## Step 1: Static detection, then triage
+
+Run the **mechanical detectors first** (cheap, deterministic greps over the
+in-scope styles and components), then apply **LLM triage** to each candidate
+against the Step 0 baseline — a mechanical hit is a *candidate*, not
+automatically a finding.
+
+### Layout & Viewport
+
+- **Viewport meta:** absent `<meta name="viewport">`, a missing
+  `width=device-width`, or `user-scalable=no` / `maximum-scale=1` pinning the
+  page against pinch-zoom.
+- **Fixed dimensions:** `width`/`min-width`/`height` px literals wider than the
+  narrowest declared breakpoint, outside token and container-query files — the
+  classic source of a page that cannot shrink.
+- **Viewport-height units:** `100vh` (or `vh` arithmetic) with no `dvh`/`svh`
+  fallback, which cuts content off under a mobile browser's collapsing toolbar.
+- **Horizontal overflow:** unconstrained wide content — tables, `<pre>` blocks,
+  code fences, flex rows with no `min-width: 0`, absolutely-positioned elements
+  extending past the viewport — and any `overflow-x: visible` on a container
+  holding them. A page whose body scrolls sideways on a phone is a defect
+  regardless of its cause.
+- **Safe-area insets:** `position: fixed`/`sticky` elements pinned to a screen
+  edge (bottom bars, floating actions, drawers, modals) with no
+  `env(safe-area-inset-*)` allowance, so a notch or home indicator overlaps
+  them.
+
+### Touch Ergonomics
+
+- **Hover-only interaction:** a `:hover`/`hover:` state that reveals content or
+  is the only affordance for an action, with no touch-reachable equivalent
+  (a click/tap handler, a focus state, or an always-visible control). On a
+  touch device that interaction does not exist.
+- **Control size and spacing:** interactive controls whose rendered box is
+  visibly under ~44×44 CSS px, or adjacent tap targets with no separating
+  spacing. Report the **measurement** as ergonomic evidence and leave the
+  WCAG `2.5.8` verdict to the accessibility lens.
+- **Input ergonomics:** form inputs with a font-size under 16px (iOS Safari
+  zooms the whole page on focus), a missing or wrong `inputmode`/`type` for the
+  expected keyboard (numeric, email, tel), and `autocomplete` omitted on
+  identity or address fields where a small-screen user most needs it.
+- **Gesture conflicts:** custom swipe/drag handlers that call
+  `preventDefault()` on `touchstart`/`touchmove` across a scrollable region, or
+  scroll containers nested inside a horizontal pager, which strand the user's
+  scroll.
+
+### Responsive Assets
+
+- **Images:** `<img>` with no `srcset`/`sizes` (or a framework image component
+  bypassed for a raw tag) where the same file serves every width; a missing
+  intrinsic `width`/`height` or `aspect-ratio`, which shifts the layout as
+  images land.
+- **Media and embeds:** `<video>`, `<iframe>`, and map/chart embeds with fixed
+  pixel dimensions or no responsive container.
+- **Typography and spacing:** a type or spacing scale with no small-viewport
+  step, so a desktop-tuned heading dominates a phone screen.
+
+> **Detector output is candidates.** Triage each against the Step 0 baseline
+> before promoting it to a finding — a fixed width inside a design-system
+> primitive that its container query already re-flows, a `100vh` on a
+> deliberately desktop-only admin surface, or a raw `<img>` for a fixed-size
+> icon, is expected, not a defect.
+
+## Step 2: Mobile verification coverage & effectiveness
+
+A responsive surface with nothing holding it responsive regresses on the next
+change. This lens owns that one test question, in two parts — report them as
+separate findings, because the fixes differ:
+
+1. **Coverage — is anything exercised at a non-desktop viewport?** Reconcile the
+   Step 0 device matrix against the suites that exist: an e2e config with only a
+   desktop project, a visual-regression suite with a single wide snapshot width,
+   or Gherkin features with no phone/tablet variant all mean the responsive
+   behaviour is unverified. Name the specific surfaces in scope that no
+   non-desktop run touches.
+2. **Effectiveness — does that exercise assert anything mobile-specific?** A
+   suite that merely replays its desktop assertions at 390px wide proves the
+   page renders, not that it works. Look for assertions that could only pass on
+   a small viewport: the drawer or hamburger nav opening in place of the desktop
+   bar, the absence of horizontal document scroll, a bottom bar clearing the
+   safe area, an orientation change, a swipe or long-press gesture, a
+   viewport-conditional element being hidden or shown. A mobile project whose
+   assertions are viewport-agnostic is a **false-confidence** finding: it is
+   reported even though the suite is green, and it is usually more valuable than
+   a missing-coverage finding, because the project believes it is covered.
+
+Keep the generic test verdicts out of this step — pyramid balance, flake, and
+overall coverage gaps belong to [`/audit-quality`](audit-quality.md). Where a
+fix is a new test, name the viewport and the assertion it should make, not just
+"add mobile tests".
+
+## Step 3: Runtime viewport pass (optional corroboration)
+
+Static detection is the default and always runs. The runtime pass is
+**conditional** — it runs only when a live target is configured; its absence
+never blocks the static report.
+
+1. **Resolve the target from config — never a hardcoded URL.** Resolve the
+   target through the consumer's `qa.environments.<env>.baseUrl` (via
+   [`resolveQaEnvironment`](../scripts/lib/qa/resolve-qa-contract.js), the same
+   resolver `/qa-run` uses): an `<env>` argument resolves by exact name or
+   origin match; with no argument, enumerate `name → baseUrl` and let the
+   operator pick. If **no** `qa.environments` target is configured, **skip this
+   step** and note in the report that runtime corroboration was unavailable —
+   do not invent a URL and do not start an arbitrary dev server.
+2. **Sample routes from the navigability SSOT.** Draw the routes to exercise
+   from the consumer's route/nav registry (`planning.navigation.navRegistry` /
+   `routeGlobs` — the same SSOT [`/audit-navigability`](audit-navigability.md)
+   reads), sampling a representative set (key personas' landing routes plus any
+   route in the change-set scope) rather than a single hardcoded page.
+3. **Drive two form factors per route.** Emulate a **phone** and a **tablet**
+   viewport — `mcp__chrome-devtools__emulate` for a device profile, or
+   `resize_page` for an explicit width/height — then, per route and viewport:
+   take a screenshot, and evaluate the two observables static analysis cannot
+   resolve — whether `document.scrollingElement.scrollWidth` exceeds the
+   viewport width (horizontal overflow), and the rendered box of the
+   interactive controls Step 1 flagged as candidates. Reload after switching
+   form factor so load-time device gates re-run.
+4. **Median-of-3 or provisional.** Any runtime measurement is subject to
+   run-to-run variance: capture a **median-of-3** (three runs per route, report
+   the median) before treating a number as authoritative. A single-run value is
+   reported **provisional** and never drives a Critical/High verdict on its own.
+5. **Leave the viewport as you found it.** Reset the emulation before finishing
+   so a following lens or QA run does not inherit a phone viewport.
+
+Corroborate static findings against the runtime observations (a statically
+flagged fixed width confirmed by a real horizontal overflow graduates from
+provisional to confirmed), and surface runtime-only defects the static pass
+could not see — an element clipped only once the toolbar collapses, a drawer
+that opens off-screen.
+
+## Report additions
+
+Beyond the shared skeleton, the Executive Summary states the runtime mode's
+status (ran against `<env>` / skipped — no target configured) and names the
+narrowest breakpoint the project declares, so a reader can tell what "mobile"
+meant for this run. The report ends with a **Runtime Viewport Pass** section:
+per-route, per-form-factor observations when the runtime mode ran, or
+"*Runtime corroboration unavailable — no `qa.environments` target configured.*"
+Drop every claimed finding that names no concrete element, style rule, or test
+file.

package/.agents/workflows/audit-ux-ui.md

@@ -89,12 +89,17 @@ baseline — a mechanical hit is a *candidate*, not automatically a finding.
 2. **Error States:** Are form errors clear and helpful, or generic and
    frustrating?
 3. **Loading States:** Are there skeletons or spinners for async operations?
-4. **Responsiveness:** Check layouts at mobile, tablet, and desktop breakpoints.
-5. **Accessibility (UX-focused):** Focus on tab order, touch-target sizes, and
-   whether interaction colours come from a sanctioned token. **WCAG conformance
-   is out of scope here** — semantic structure, ARIA correctness,
-   keyboard/focus operability, form labelling, media alternatives, and the WCAG
-   contrast-ratio verdict are owned by [`/audit-accessibility`](audit-accessibility.md).
+4. **Accessibility (UX-focused):** Focus on tab order and whether interaction
+   colours come from a sanctioned token. **WCAG conformance is out of scope
+   here** — semantic structure, ARIA correctness, keyboard/focus operability,
+   form labelling, media alternatives, and the WCAG contrast-ratio verdict are
+   owned by [`/audit-accessibility`](audit-accessibility.md).
    This lens keeps token/component design-system adherence; defer every WCAG
    success-criterion judgement to the accessibility lens so the two never
    double-report.
+
+> **Small-screen behaviour is out of scope here too.** Layout at a phone or
+> tablet viewport, touch-target ergonomics, responsive assets, and whether any
+> suite exercises a non-desktop viewport belong to [`/audit-mobile`](audit-mobile.md).
+> This lens keeps the token/component question at whatever viewport the surface
+> renders.

package/docs/CHANGELOG.md

@@ -15,6 +15,13 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.51.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.50.0...mandrel-v2.51.0) (2026-09-08)
+
+
+### Added
+
+* **audit:** add the /audit-mobile lens for mobile and tablet UX (refs [#5233](https://github.com/dsj1984/mandrel/issues/5233)) ([#5234](https://github.com/dsj1984/mandrel/issues/5234)) ([eccd505](https://github.com/dsj1984/mandrel/commit/eccd50527f04a25e02d50f57e1c6d760345bc9e8))
+
 ## [2.50.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.49.0...mandrel-v2.50.0) (2026-09-08)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.50.0",
+  "version": "2.51.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",