mandrel 2.4.0 → 2.5.0

package/.agents/scripts/nav-registry-diff.js

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+/**
+ * .agents/scripts/nav-registry-diff.js — the deterministic route ↔ nav-registry
+ * cross-check the navigability lens (`audit-navigability.md`) runs and triages.
+ *
+ * The navigability lens asserts two symmetric invariants over a consumer's web
+ * surface:
+ *
+ *   1. **Every route has a persona nav door** — a route registered in the route
+ *      tree that no nav-registry entry surfaces for an entitled persona is an
+ *      **orphaned route**.
+ *   2. **No nav href is dead** — a nav-registry door whose target does not
+ *      resolve to a real route is a **dead nav href**.
+ *
+ * Both invariants are a set-difference over two identifier lists, not a
+ * judgement call, so they belong in a script rather than in lens prose that
+ * asks the agent to eyeball the two files. The lens enumerates the route tree
+ * (from `planning.navigation.routeGlobs`) and the nav registry (from
+ * `planning.navigation.navRegistry`), hands both to this tool, and triages the
+ * structured diff it prints.
+ *
+ * The one subtlety a naive set-difference gets wrong is **false orphans**: a
+ * dynamic detail route (`/users/:id`) is reachable through its surfaced parent,
+ * a system route (`/login`, `/404`) is reachable by construction, and a route
+ * reached only by an in-app link is not orphaned either. This tool applies that
+ * **orphan-verification exemption taxonomy** so the lens reports only genuine
+ * orphans (Story #4630, AC-5).
+ *
+ * Input is two JSON files (route tree + nav registry); a third optional file
+ * lists in-app inbound references. Route and door **identifiers only** are read
+ * — never route bodies or persona PII (the navigability lens's logging
+ * constraint). The tool prints the diff and exits 0 on a successful run; pass
+ * `--strict` to exit non-zero when genuine findings remain (a CI gate posture).
+ *
+ * This is a one-shot deterministic reporter, not an orchestrator: it takes no
+ * ticket, mutates no state, and spawns no process.
+ */
+
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Last-segment tokens (or whole-path tokens) that mark a **system route** —
+ * reachable by construction (auth walls, error pages) rather than through a
+ * persona nav door, so their absence from the nav registry is never an orphan.
+ */
+const SYSTEM_ROUTE_TOKENS = Object.freeze([
+  'login',
+  'logout',
+  'signin',
+  'sign-in',
+  'signout',
+  'sign-out',
+  'signup',
+  'sign-up',
+  'register',
+  'auth',
+  'callback',
+  'unauthorized',
+  'forbidden',
+  'not-found',
+  'notfound',
+  '404',
+  '401',
+  '403',
+  '500',
+  'error',
+  'maintenance',
+]);
+
+/** The exemption reasons a verified non-orphan can carry, for triage clarity. */
+const EXEMPTION_REASONS = Object.freeze({
+  EXPLICIT: 'explicit-exempt',
+  SYSTEM: 'system-route',
+  DYNAMIC_CHILD: 'dynamic-child-of-surfaced-parent',
+  INBOUND: 'inbound-in-app-reference',
+});
+
+/**
+ * Normalize a route or href path for comparison: coerce to string, trim, force
+ * a single leading slash, collapse duplicate slashes, and drop a trailing slash
+ * (except for the root `/`). Returns `''` for a nullish or empty input so the
+ * caller can reject it.
+ *
+ * @param {unknown} p
+ * @returns {string}
+ */
+export function normalizePath(p) {
+  if (typeof p !== 'string') return '';
+  const trimmed = p.trim();
+  if (trimmed.length === 0) return '';
+  const withSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+  const collapsed = withSlash.replace(/\/{2,}/g, '/');
+  return collapsed.length > 1 ? collapsed.replace(/\/+$/, '') : collapsed;
+}
+
+/**
+ * Split a normalized path into its non-empty segments (`'/'` → `[]`).
+ *
+ * @param {string} normalized
+ * @returns {string[]}
+ */
+function segmentsOf(normalized) {
+  return normalized.split('/').filter(Boolean);
+}
+
+/**
+ * True when a single path segment is a **dynamic** segment: an Express/React
+ * Router `:param`, a Next.js `[param]` / `[...catchAll]`, a bare wildcard `*`,
+ * or a `{param}` template.
+ *
+ * @param {string} segment
+ * @returns {boolean}
+ */
+export function isDynamicSegment(segment) {
+  return (
+    segment.startsWith(':') ||
+    segment === '*' ||
+    (segment.startsWith('[') && segment.endsWith(']')) ||
+    (segment.startsWith('{') && segment.endsWith('}'))
+  );
+}
+
+/** True when the segment is a catch-all (`[...slug]` / `*`) that eats the rest. */
+function isCatchAllSegment(segment) {
+  return segment === '*' || segment.startsWith('[...');
+}
+
+/**
+ * True when a normalized route path contains at least one dynamic segment.
+ *
+ * @param {string} normalized
+ * @returns {boolean}
+ */
+export function isDynamicPath(normalized) {
+  return segmentsOf(normalized).some(isDynamicSegment);
+}
+
+/**
+ * True when a normalized route path is a system route (its last segment, or the
+ * whole path, is a recognized system token).
+ *
+ * @param {string} normalized
+ * @returns {boolean}
+ */
+export function isSystemRoute(normalized) {
+  const segs = segmentsOf(normalized);
+  if (segs.length === 0) return false;
+  const last = segs[segs.length - 1].toLowerCase();
+  return SYSTEM_ROUTE_TOKENS.includes(last);
+}
+
+/**
+ * The parent of a normalized path — the path with its last segment removed
+ * (`/users/:id` → `/users`, `/users` → `/`, `/` → `/`).
+ *
+ * @param {string} normalized
+ * @returns {string}
+ */
+export function parentPath(normalized) {
+  const segs = segmentsOf(normalized);
+  if (segs.length <= 1) return '/';
+  return `/${segs.slice(0, -1).join('/')}`;
+}
+
+/**
+ * True when a **route template** (which may contain dynamic segments) matches a
+ * concrete **href**. A dynamic segment matches any single href segment; a
+ * catch-all matches one-or-more trailing href segments. A template with no
+ * dynamic segment matches only an identical href.
+ *
+ * @param {string} routeNorm normalized route path (the template)
+ * @param {string} hrefNorm normalized href (the concrete target)
+ * @returns {boolean}
+ */
+export function routeTemplateMatchesHref(routeNorm, hrefNorm) {
+  const routeSegs = segmentsOf(routeNorm);
+  const hrefSegs = segmentsOf(hrefNorm);
+  for (let i = 0; i < routeSegs.length; i += 1) {
+    const rSeg = routeSegs[i];
+    if (isCatchAllSegment(rSeg)) {
+      // A catch-all consumes every remaining href segment (>= 1).
+      return hrefSegs.length >= i + 1;
+    }
+    if (i >= hrefSegs.length) return false;
+    if (isDynamicSegment(rSeg)) continue; // matches any one segment
+    if (rSeg !== hrefSegs[i]) return false;
+  }
+  return routeSegs.length === hrefSegs.length;
+}
+
+/**
+ * Coerce a route-tree entry (a bare path string or a `{ path, personas, exempt,
+ * kind }` object) into the internal route shape. Throws on an entry with no
+ * usable path so a malformed fixture fails loudly rather than silently
+ * dropping a route.
+ *
+ * @param {unknown} entry
+ * @returns {{ path: string, personas: string[], exempt: boolean }}
+ */
+export function toRoute(entry) {
+  const raw = typeof entry === 'string' ? { path: entry } : (entry ?? {});
+  const path = normalizePath(raw.path);
+  if (path === '') {
+    throw new Error(
+      `nav-registry-diff: route entry has no usable "path": ${JSON.stringify(entry)}`,
+    );
+  }
+  const personas = Array.isArray(raw.personas)
+    ? raw.personas.filter((x) => typeof x === 'string' && x.trim().length > 0)
+    : [];
+  return { path, personas, exempt: raw.exempt === true };
+}
+
+/**
+ * Coerce a nav-registry entry (a bare href string or a `{ href, persona }`
+ * object) into the internal door shape. Throws on an entry with no usable href.
+ *
+ * @param {unknown} entry
+ * @returns {{ href: string, persona: string|null }}
+ */
+export function toDoor(entry) {
+  const raw = typeof entry === 'string' ? { href: entry } : (entry ?? {});
+  const href = normalizePath(raw.href ?? raw.path);
+  if (href === '') {
+    throw new Error(
+      `nav-registry-diff: nav entry has no usable "href": ${JSON.stringify(entry)}`,
+    );
+  }
+  const persona =
+    typeof raw.persona === 'string' && raw.persona.trim().length > 0
+      ? raw.persona.trim()
+      : null;
+  return { href, persona };
+}
+
+/**
+ * True when a nav door surfaces a route: the door's href resolves to the route
+ * (identical path, or the route template matches the concrete href), AND — when
+ * both sides name personas — the door renders in a persona entitled to the
+ * route. A route with no declared personas is surfaced by any resolving door; a
+ * door with no persona surfaces for any entitled persona.
+ *
+ * @param {{ path: string, personas: string[] }} route
+ * @param {{ href: string, persona: string|null }} door
+ * @returns {boolean}
+ */
+function doorSurfacesRoute(route, door) {
+  const resolves =
+    route.path === door.href || routeTemplateMatchesHref(route.path, door.href);
+  if (!resolves) return false;
+  if (route.personas.length === 0 || door.persona === null) return true;
+  return route.personas.includes(door.persona);
+}
+
+/**
+ * Resolve why an unsurfaced route is exempt from the orphan report, or `null`
+ * when it is a genuine orphan. The taxonomy (Story #4630, AC-5): an explicitly
+ * exempt route, a system route, a dynamic-segment child of a surfaced parent,
+ * or a route reached by an in-app inbound reference.
+ *
+ * @param {{ path: string, exempt: boolean }} route
+ * @param {Set<string>} surfacedPaths route paths a door surfaces
+ * @param {Set<string>} inboundRefs normalized in-app referenced paths
+ * @returns {string|null} an {@link EXEMPTION_REASONS} value, or null
+ */
+function orphanExemption(route, surfacedPaths, inboundRefs) {
+  if (route.exempt) return EXEMPTION_REASONS.EXPLICIT;
+  if (isSystemRoute(route.path)) return EXEMPTION_REASONS.SYSTEM;
+  if (isDynamicPath(route.path) && surfacedPaths.has(parentPath(route.path))) {
+    return EXEMPTION_REASONS.DYNAMIC_CHILD;
+  }
+  if (inboundRefs.has(route.path)) return EXEMPTION_REASONS.INBOUND;
+  return null;
+}
+
+/**
+ * Compute the two-way route ↔ nav-registry diff with orphan verification.
+ *
+ * @param {{
+ *   routes?: unknown[],
+ *   nav?: unknown[],
+ *   refs?: unknown[],
+ * }} params
+ * @returns {{
+ *   counts: { routes: number, doors: number },
+ *   orphanedRoutes: { path: string, personas: string[] }[],
+ *   deadHrefs: { href: string, persona: string|null }[],
+ *   exemptRoutes: { path: string, reason: string }[],
+ * }}
+ */
+export function computeNavDiff({ routes = [], nav = [], refs = [] } = {}) {
+  const routeList = routes.map(toRoute);
+  const doorList = nav.map(toDoor);
+  const inboundRefs = new Set(refs.map(normalizePath).filter((p) => p !== ''));
+
+  // Which route paths does at least one door surface (persona-aware)?
+  const surfacedPaths = new Set();
+  for (const route of routeList) {
+    if (doorList.some((door) => doorSurfacesRoute(route, door))) {
+      surfacedPaths.add(route.path);
+    }
+  }
+
+  const orphanedRoutes = [];
+  const exemptRoutes = [];
+  for (const route of routeList) {
+    if (surfacedPaths.has(route.path)) continue;
+    const reason = orphanExemption(route, surfacedPaths, inboundRefs);
+    if (reason === null) {
+      orphanedRoutes.push({ path: route.path, personas: route.personas });
+    } else {
+      exemptRoutes.push({ path: route.path, reason });
+    }
+  }
+
+  // A door is dead when its href resolves to no route (identical or template).
+  const deadHrefs = [];
+  for (const door of doorList) {
+    const resolves = routeList.some(
+      (route) =>
+        route.path === door.href ||
+        routeTemplateMatchesHref(route.path, door.href),
+    );
+    if (!resolves) deadHrefs.push({ href: door.href, persona: door.persona });
+  }
+
+  return {
+    counts: { routes: routeList.length, doors: doorList.length },
+    orphanedRoutes,
+    deadHrefs,
+    exemptRoutes,
+  };
+}
+
+/**
+ * Read and parse a JSON array from a file, throwing a clear error when the file
+ * is unreadable, not JSON, or not an array.
+ *
+ * @param {string} label human-readable role for the error message
+ * @param {string} file
+ * @returns {unknown[]}
+ */
+function readJsonArray(label, file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `nav-registry-diff: cannot read ${label} file '${file}': ${err.message}`,
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `nav-registry-diff: ${label} file '${file}' is not valid JSON: ${err.message}`,
+    );
+  }
+  // Accept either a bare array or a `{ routes: [...] }` / `{ nav: [...] }` wrapper.
+  const list = Array.isArray(parsed)
+    ? parsed
+    : (parsed?.routes ?? parsed?.nav ?? parsed?.entries);
+  if (!Array.isArray(list)) {
+    throw new Error(
+      `nav-registry-diff: ${label} file '${file}' must be a JSON array (or an object with a matching array field)`,
+    );
+  }
+  return list;
+}
+
+/**
+ * Render the diff as a human-readable, triage-friendly text report.
+ *
+ * @param {ReturnType<typeof computeNavDiff>} diff
+ * @returns {string}
+ */
+export function formatDiffText(diff) {
+  const lines = [
+    'Route ↔ nav-registry diff',
+    `  routes: ${diff.counts.routes}   nav doors: ${diff.counts.doors}`,
+    `  orphaned routes: ${diff.orphanedRoutes.length}`,
+  ];
+  for (const o of diff.orphanedRoutes) {
+    const personas = o.personas.length > 0 ? ` [${o.personas.join(', ')}]` : '';
+    lines.push(`    - ${o.path}${personas}`);
+  }
+  lines.push(`  dead nav hrefs: ${diff.deadHrefs.length}`);
+  for (const d of diff.deadHrefs) {
+    const persona = d.persona ? ` [${d.persona}]` : '';
+    lines.push(`    - ${d.href}${persona}`);
+  }
+  lines.push(`  exempt (verified, not reported): ${diff.exemptRoutes.length}`);
+  for (const e of diff.exemptRoutes) {
+    lines.push(`    - ${e.path} — ${e.reason}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * @param {string[]} argv
+ * @returns {Promise<number>} process exit code
+ */
+async function main(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      routes: { type: 'string' },
+      nav: { type: 'string' },
+      refs: { type: 'string' },
+      json: { type: 'boolean', default: false },
+      strict: { type: 'boolean', default: false },
+    },
+    allowPositionals: false,
+  });
+
+  if (!values.routes || !values.nav) {
+    throw new Error(
+      'nav-registry-diff: both --routes <file> and --nav <file> are required.\n' +
+        'Usage: node .agents/scripts/nav-registry-diff.js --routes routes.json --nav nav.json [--refs refs.json] [--json] [--strict]',
+    );
+  }
+
+  const routes = readJsonArray('routes', values.routes);
+  const nav = readJsonArray('nav', values.nav);
+  const refs = values.refs ? readJsonArray('refs', values.refs) : [];
+
+  const diff = computeNavDiff({ routes, nav, refs });
+
+  // Written straight to stdout (not the orchestrator Logger) so the output is a
+  // clean, machine-parseable report the lens can pipe or `JSON.parse`.
+  const rendered = values.json
+    ? JSON.stringify(diff, null, 2)
+    : formatDiffText(diff);
+  process.stdout.write(`${rendered}\n`);
+
+  const hasFindings =
+    diff.orphanedRoutes.length > 0 || diff.deadHrefs.length > 0;
+  return values.strict && hasFindings ? 1 : 0;
+}
+
+export { main };
+
+runAsCli(import.meta.url, main, {
+  source: 'nav-registry-diff',
+  propagateExitCode: true,
+});

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

@@ -0,0 +1,243 @@
+---
+description: Audit WCAG accessibility conformance (static-first) with an optional runtime verification pass, and produce a structured findings report
+---
+
+# Accessibility (WCAG) Audit
+
+## 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 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.
+
+## Role
+
+Senior Accessibility Engineer. You hold the frontend to **WCAG 2.x
+conformance** — semantic structure, ARIA correctness, keyboard operability,
+form labelling, media alternatives, and contrast — grounding every finding in a
+concrete element and the success criterion it violates. You default to
+**static** detection over the source, and escalate to a **runtime** pass only
+when a live target is configured.
+
+## Context & Objective
+
+This is a **read-only** audit. Detect WCAG violations statically from the
+component/template/route source, optionally corroborate them against a running
+build, and emit a structured Markdown report at
+`{{auditOutputDir}}/audit-accessibility-results.md`. Do not modify application
+code — surfacing the violations (each keyed to a WCAG success criterion) is the
+deliverable; fixing them is a separate pass.
+
+> **No conformance certification.** The lens reports findings against WCAG
+> success criteria; it does **not** assert a conformance level (A / AA / AAA)
+> for the product. "No findings in scope" is not "certified conformant".
+
+## Boundary with `audit-ux-ui`
+
+These two web lenses share a border and must not double-report:
+
+- **`audit-accessibility` (this lens)** owns **WCAG conformance** — the
+  standards question: does an assistive-technology user perceive, operate, and
+  understand the surface? Semantic HTML, ARIA, keyboard/focus, labelled
+  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
+  (hardcoded values that bypass a token, raw elements that should defer to a
+  design-system component, interaction/loading/error states, premium feel)?
+
+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.
+
+## Scope (Story / plan-run mode)
+
+When this lens is invoked from `/deliver` close lenses (or a plan-run audit), the
+following block is populated with the Story (or plan-run) change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to those files (and their direct dependencies
+  when the lens explicitly calls for cross-file reasoning).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full codebase-wide scan defined in the remaining
+  steps.
+
+## Step 0: Discover the frontend surface and config (run first)
+
+**You cannot audit WCAG conformance until you have located what renders and how
+the project is configured.** Before any detection:
+
+- **Renderable surface:** the component directories (`components/**`,
+  `app/**`, `pages/**`, `src/**`), templates (`**/*.html`, `**/*.astro`,
+  framework SFCs), and any design-system component library raw elements are
+  expected to defer to.
+- **Static a11y tooling already in the repo:** an `eslint-plugin-jsx-a11y`
+  config, an `axe-core` / `@axe-core/*` dependency, or a `pa11y` config. Prefer
+  reusing the consumer's configured ruleset over inventing one.
+- **Design tokens:** the colour tokens (`tailwind.config.*`, CSS custom
+  properties, a theme object) whose literal values you need to compute contrast
+  ratios statically.
+- **Runtime target (optional):** the `qa.environments` map (see
+  [_Runtime verification mode_](#step-2-runtime-verification-mode-optional-corroboration))
+  and the navigability route SSOT.
+
+Record what exists. Every finding downstream is measured against _this
+discovered surface and config_, not a generic ideal. If **no** frontend surface
+exists in scope, say so and emit an empty report rather than inventing findings.
+
+## Step 1: Static WCAG detection, then triage
+
+> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
+
+Run the **mechanical detectors first** (cheap, deterministic greps and the
+static a11y linters discovered in Step 0), then apply **LLM triage** to each
+candidate — a mechanical hit is a _candidate_, not automatically a finding.
+Cover every static WCAG dimension:
+
+- **Semantic structure** (WCAG 1.3.1) — landmark regions (`<main>`, `<nav>`,
+  `<header>`), a single `<h1>` and a non-skipping heading order, lists for
+  list-shaped content, and `<button>`/`<a>` used for their real role rather
+  than a clickable `<div>`/`<span>`.
+- **ARIA correctness** (WCAG 4.1.2) — census `role=` / `aria-*` usage: invalid
+  roles, `aria-*` attributes unsupported on their element, `aria-labelledby` /
+  `aria-describedby` pointing at absent ids, redundant roles on native
+  elements, and interactive `role=` on a non-focusable element.
+- **Keyboard operability & focus management** (WCAG 2.1.1 / 2.4.3 / 2.4.7) —
+  click handlers on non-interactive elements with no keyboard handler or
+  `tabindex`, positive `tabindex` values, `:hover`/`hover:` states with no
+  matching `:focus-visible`/`focus-visible:`, focus traps, and `outline: none`
+  with no replacement focus indicator.
+- **Forms & labels** (WCAG 1.3.1 / 3.3.2 / 4.1.2) — inputs with no associated
+  `<label for>` / wrapping label / `aria-label`, placeholder-as-label,
+  unlabelled control groups (`fieldset`/`legend`), and error text not tied to
+  its field.
+- **Media alternatives** (WCAG 1.1.1 / 1.2.x) — `<img>` with no `alt`
+  (and decorative images missing `alt=""`), `<video>`/`<audio>` with no
+  captions/transcript track, `<svg>` conveying meaning with no accessible name,
+  and icon-only controls with no accessible name.
+- **Contrast where statically derivable** (WCAG 1.4.3 / 1.4.11) — when both the
+  foreground and background resolve to concrete token/literal colour values,
+  compute the ratio and flag body text below 4.5:1, large text below 3:1, and
+  non-text/UI boundaries below 3:1. When either colour cannot be resolved
+  statically (runtime theme, image background), mark it **provisional** and
+  defer confirmation to Step 2 rather than guessing.
+- **Raw-element census** — when the project configures a static ruleset,
+  reconcile the raw-element findings above against the design-system components
+  that already encode the accessible pattern, so the fix lands in one place.
+
+> **Detector output is candidates.** Triage each against the Step 0 surface and
+> the specific WCAG success criterion before promoting it to a finding — a role
+> on a design-system primitive that already manages focus, or a token `px` value
+> inside a token file, is expected, not a defect.
+
+## Step 2: Runtime verification mode (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. **Run an accessibility engine per sampled route.** Use the
+   `mcp__chrome-devtools__lighthouse_audit` tool's **Accessibility category**,
+   or run **axe** via the browser tooling, against each sampled `baseUrl`-rooted
+   route. Prefer a production-mode build.
+4. **Median-of-3 or provisional.** Any runtime score or metric 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.
+
+Corroborate static findings against the runtime results (a statically-flagged
+contrast defect confirmed by the engine graduates from provisional to
+confirmed), and surface runtime-only violations the static pass could not see.
+
+## Step 3: Output Requirements
+
+Generate and save a structured Markdown report to
+`{{auditOutputDir}}/audit-accessibility-results.md`, using the exact template
+below. The report MUST include all sections, even if empty (write
+"_No findings._" rather than omitting a section).
+
+> Grade every finding's severity on the shared
+> [`Critical | High | Medium | Low` scale](helpers/audit-severity-scale.md), and
+> key every finding to the WCAG success criterion it violates.
+
+```markdown
+# Accessibility (WCAG) Audit report
+
+## Executive Summary
+
+[Overview of WCAG conformance health across the scope, the runtime mode's
+status (ran against `<env>` / skipped — no target configured), and the
+self-cross-check line.]
+
+## Detailed Findings
+
+[For every WCAG violation identified, use the following strict structure. Lead
+each title with the primary file the finding lives in:]
+
+### `path/to/primary-file.ext` — [Short title of the issue]
+
+- **Dimension:** [e.g., Semantic Structure | ARIA | Keyboard & Focus | Forms & Labels | Media Alternatives | Contrast]
+- **Severity:** [Critical | High | Medium | Low]
+- **WCAG:** [success criterion — e.g. `1.1.1 Non-text Content (A)`]
+- **Location:** `path/to/primary-file.ext:line`
+- **Evidence:** [measured | static] [the observable — a quoted element, the
+  computed contrast ratio, the failing axe/Lighthouse audit id + median score.
+  Runtime numbers from a single run are tagged `provisional`.]
+- **Current State:** [what is implemented and why it fails the criterion]
+- **Recommendation & Rationale:** [the specific change — attribute to add,
+  element to swap, token to adjust — and the assistive-technology behaviour it
+  restores]
+- **Acceptance signal:** [the command or observable that proves this finding is
+  remediated — e.g. the axe rule now passing on the route, or a re-run of this
+  lens]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this a11y fix independently]`
+
+## Runtime Verification
+
+[Per-route median-of-3 accessibility scores when the runtime mode ran, or
+"_Runtime corroboration unavailable — no `qa.environments` target configured._"]
+```
+
+## Constraint
+
+This is a **read-only** audit. Provide the critique and implementation
+suggestions, but do not modify components, styles, or configuration. The
+runtime mode runs **non-mutating** measurements only and starts no arbitrary
+dev server.
+
+## Self-cross-check (mandatory — filter false positives before you finalize)
+
+Before you write the report artifact from the previous step, run the shared
+adversarial self-cross-check over your Detailed Findings — see
+[`helpers/audit-self-check.md`](helpers/audit-self-check.md). It defines the
+per-finding evidence bar, the exclusion list, and the final re-open-and-drop
+pass whose `kept <k> / dropped <d>` counts you record in the Executive
+Summary, so the sequential single-pass path filters unverified findings just as
+the orchestrated path's adversarial reviewer does. Drop every claimed
+violation that names no concrete element and no specific WCAG success
+criterion.