UX Audit — suite roll-up

Run the auditor suite against one target and merge the results. By default this fans out to usability, accessibility, and cuj; web performance is opt-in (add --only web-performance or --all). This is the fan-out the report contract was built for: every auditor writes the same schema into .ux/audits/, so their reports are comparable and can be rolled up into a single verdict.

Two native auditors plus two wrapped from web-quality-skills (the same-author companion to agent-skills, a coherent suite of web-quality checks):

Extensible: web-quality-skills also ships seo and best-practices; add them as future suite members the same way (register their frameworks in scripts/validate_report.py).

Inputs

• target — a URL (preferred; a11y and web-perf need a render) or a repo path. Omit to infer from the running dev server / repo.
• --scope — narrow to a flow or area, shared by all auditors.
• --only <list> — run a subset, e.g. --only usability,accessibility. Default (no --only): usability, accessibility, and cuj — web performance is excluded (opt-in). Naming web-performance in --only runs it.
• --all — run every available auditor, including web performance. If both --only and --all are given, --only wins (the explicit subset is honored; --all is ignored).
• --mode — passed through to auditors that support it (usability).

Workflow

1. Discover available auditors. Usability is always available (native). For accessibility and web performance, check whether the wrapping skills (web-quality-skills:accessibility, web-quality-skills:performance) are installed. Web performance is also opt-in: even when installed, it runs only when named in --only or when --all is passed — it is excluded from the default bundle (its metrics are typically dev-mode / localhost lab numbers, not production Core Web Vitals). When it is not opted into, record it as skipped with the reason "web performance is opt-in; run with --only web-performance or --all", exactly as the CUJ skip is disclosed. The CUJ auditor (audit-cuj) is native but conditional: it runs only when the host has authored journeys — .ux/cujs/ exists and is non-empty. Skip any auditor that is unavailable — a wrapped skill not installed, .ux/cujs/ absent/empty, or web performance not opted into — and record it as skipped with a note giving the reason in the roll-up (for CUJ: "no CUJs authored; run /ux-spec"). A missing, skipped, or opt-in-not-requested auditor must never read as a clean pass. Honor --only and --all.

2. Auth pre-flight — once, before any auditor runs. Applies only when this run will actually drive a browser: target is a URL (or a reachable running app) and the resolved mode is live or hybrid. A repo-path target, or --mode static, has no page to navigate and no session to establish — skip this step entirely and record nothing. Do not start a dev server or open a browser just to run the probe; that is the ask-first boundary below, and a static run is not owed a browser.

   Otherwise: navigate to target (honoring --scope) and check for a login wall. If one stands there, run the auth handoff now: auth-handoff.md — observe the wall verbatim, ask once, the user signs in, re-observe to confirm the session holds.

   Before the fan-out, not inside it. Every auditor shares this browser session, so a lazy handoff would interrupt the user partway through a multi-auditor run — after minutes of work — and could ask more than once as each auditor hit the same wall independently. One probe, one interruption, before any auditor starts.

   Outcome	Then
   Not applicable (repo-path target, or static mode)	Proceed. Nothing to record.
   No wall	Proceed. Nothing to record.
   Handoff succeeded	Proceed. Every auditor inherits the session, native and wrapped alike.
   Declined	Proceed unauthenticated — do not skip the run. Auditors cover what is reachable and disclose the gated screens as coverage gaps.
   No attended browser surface	Same as declined, with cause handoff unavailable — no attended browser surface. Not a decline; nobody was asked.

   Disclose it in the roll-up. Carry the outcome into the roll-up summary as an Access: line, so the priority distribution is never read as covering the whole product when it covered only the public half. Record the rung, never the account.

   A note on the wrapped auditors. web-quality-skills:accessibility and :performance inherit the session but do not know this suite's capture rules, so their own artifacts may carry account data. That is why the artifact posture (auth-handoff.md §6) recommends ignoring .ux/audits/ wholesale rather than assets-only, and why the recommendation is made here — at auth time, before any auditor writes anything.

3. Fan out. Run each selected auditor against the same target/--scope:
   • Usability — invoke the native usability-audit skill; it already writes a contract report.
   • Accessibility — invoke web-quality-skills:accessibility; capture its WCAG findings.
   • Web performance (only when opted in via --only web-performance or --all) — invoke web-quality-skills:performance (and core-web-vitals); capture its findings, respecting its metric-honesty rule (unmeasured = potential, never fabricated).
   • Critical user journeys — invoke the native audit-cuj skill; it replays the host's .ux/cujs/ and already writes a contract report. It honors its own static-vs-live honesty rule (a static run cannot produce a verified pass).
4. Normalize into the shared contract. For each wrapped auditor, write a contract-conforming report at .ux/audits/<auditor>-<YYYYMMDD>-<HHMMSS>.md — same frontmatter schema, body layout, and appendix. Map each tool's output onto the P0–P3 ladder — these tools never produced a severity in the first place; they produce conformance failures and measured bands, which are statements about task impact:
   • Accessibility (WCAG): a blocker on a core flow, or a Level A name-role-value failure that leaves no route through → P0; other Level A, and Level AA (e.g. 1.4.3 contrast) → P1; minor/AAA or edge → P2; cosmetic → P3.
   • Web performance: a Core Web Vital in the "poor" band (measured) → P1; "needs improvement" → P2; a structural anti-pattern with only potential impact → P2–P3, labeled potential per the metric-honesty rule.
   • Severity still has to be rated, not copied from the priority: apply the contract's three factors to what the tool found. A contrast failure on every page is persistent and frequent even when a workaround exists.
   • Omit non-problems entirely (severity 0), same as usability. Set auditor and frameworks per the table above; carry the tool's evidence (screenshots, file:line, measured metrics) into the Evidence field. The native auditors (usability, cuj) already emit contract reports — no external remapping. CUJ carries one exception the roll-up must respect: total: 0 is a pass (every journey verified clean), not "found nothing". Read the CUJ report's executive-summary counts and frameworks list to tell a clean pass from a run that verified nothing (frameworks: [cuj-contract] alone signals the latter), and never fold a skipped CUJ run into the passed column.
5. Append the index. Add one .ux/audits/index.md row per auditor run (append-only), exactly as a single-auditor run does.

6. Write the roll-up. Create .ux/audits/rollup-<YYYYMMDD>-<HHMMSS>.md with this frontmatter:

   ---
   rollup: true                 # REQUIRED — see below
   date: 2026-11-12T02:12:05Z   # ISO-8601, UTC, from the runtime clock
   target: http://localhost:3000
   scope: "whole app — default bundle (usability, accessibility, cuj)"
   auditors_run: [usability, accessibility, cuj]
   auditors_skipped:
     - "web-performance — opt-in; run with --only web-performance or --all"
   priorities:                  # the P0-P3 totals across every auditor that ran
     P0: 0
     P1: 1
     P2: 3
     P3: 1
   ---

   rollup: true is load-bearing and its absence is silent. render_report_html.py branches on that one key to pick the dashboard view. Omit it and the file still renders — as an ordinary report, minus the headline banner that names the highest-priority finding and warns when auditors were skipped. Nothing fails; the warning simply is not there. Step 7's --rollup check exists to make that loud.

   There is no verdict: key — see the no-ship-call rule below.

   The body holds:

   • The priority distribution — per-auditor counts plus a total row, e.g. 1 x P0 - 4 x P1 - 7 x P2 - 2 x P3. This is the headline.
   • The highest-priority finding, named. A count says how much; it does not say what broke. Quote the worst finding with its auditor and link, so the reader sees the thing itself and can disagree with its rank.
   • A merged issues list ordered by priority across all auditors.
   • Coverage — which auditors ran, which were skipped and why (a CUJ run skipped for want of .ux/cujs/; web performance skipped when not opted into, with its opt-in reason), and the Access: rung from step 2.

   No overall go/no-go verdict, and this is deliberate. Whether a release ships needs release context the suite does not have — deadlines, risk appetite, what the alternative costs — and inventing one is exactly what Boundaries forbids. The roll-up answers what do I fix first; the ship call stays with the human.

   An empty distribution is not automatically a pass. A skipped CUJ run, a web-performance run not opted into, or an uninstalled auditor is disclosed next to the counts, never folded into a clean read: 0 x P0 across one auditor of four says almost nothing about the product. The same discriminator the CUJ reports use (a verified pass is not a run that verified nothing) applies to the suite as a whole. Link to each report.

7. Self-check. Validate each artifact with scripts/validate_report.py — three modes, and the roll-up needs its own:

   python3 scripts/validate_report.py .ux/audits/<auditor>-*.md   # the member reports
   python3 scripts/validate_report.py --rollup .ux/audits/rollup-*.md
   python3 scripts/validate_report.py --index .ux/audits/index.md

   A roll-up is not a report — it carries no auditor, mode, frameworks or findings — so passing it to the bare form reports a page of irrelevant errors. Use --rollup, which checks what a roll-up actually promises: the rollup: true key, the priorities totals, the auditors ran/skipped lists, the two required sections, and the absence of a reinstated verdict.

   Then confirm the safety invariant with scripts/audit_safety.py <host-repo>. It checks both halves of the invariant (SPEC §5.2) and exits 0 only if both hold: nothing changed outside .ux/audits/, and the writes you just made inside it were observed — it prints them. Exit 1 with "no writes were observed" means the run produced nothing; that is a real failure for an auditor, not a formality, and it is the only signal you get once .ux/audits/ is gitignored and git status has gone quiet.

8. Render the HTML companions. Generate a self-contained HTML view for every member report, the roll-up dashboard (with its priority distribution and per-auditor matrix linking to each member's .html), and the index landing page:

   python3 scripts/render_report_html.py .ux/audits/*.md
   python3 scripts/render_report_html.py --index .ux/audits/index.md

   Each .html is a derived view of its Markdown, written under .ux/audits/ — the safety invariant holds. (Also available on demand via /ux-review.)

Boundaries

• Findings only. No auditor in the roll-up edits host application code.
• Never write outside .ux/audits/ in the host repo — the suite-wide safety invariant.
• Ask first before starting a dev server, navigating a browser, or installing anything (including a missing wrapped skill — offer, don't auto-install).
• Never fabricate, and honor each wrapped auditor's own honesty rules (usability's render-vs-source; web performance's metric-honesty).

Exit criteria (done when)

• Each selected, available auditor produced a contract-valid report under .ux/audits/, with one appended index row apiece.
• A rollup-<timestamp>.md exists with the priority distribution, the highest-priority finding named, skipped auditors (with reasons), merged issues, and no ship call.
• Every member report validates, the roll-up validates under --rollup, and the index validates under --index; audit_safety.py exits 0 on both halves: nothing changed outside .ux/audits/, and the reports this run wrote inside it were observed.