@diegovelasquezweb/a11y-engine 0.10.2 → 0.11.1

package/assets/scanning/cdp-checks.mjs

@@ -1 +1,60 @@
-export default {"interactiveRoles":["button","link","textbox","combobox","listbox","menuitem","tab","checkbox","radio","switch","slider"],"rules":[{"id":"cdp-missing-accessible-name","condition":"interactive-no-name","impact":"serious","tags":["wcag2a","wcag412","cdp-check"],"help":"Interactive elements must have an accessible name","helpUrl":"https://dequeuniversity.com/rules/axe/4.11/button-name","description":"Interactive element with role \"{{role}}\" has no accessible name","failureMessage":"Element with role \"{{role}}\" has no accessible name in the accessibility tree","axeEquivalents":["button-name","link-name","input-name","aria-command-name"]},{"id":"cdp-aria-hidden-focusable","condition":"hidden-focusable","impact":"serious","tags":["wcag2a","wcag412","cdp-check"],"help":"aria-hidden elements must not be focusable","helpUrl":"https://dequeuniversity.com/rules/axe/4.11/aria-hidden-focus","description":"Focusable element with role \"{{role}}\" is aria-hidden","failureMessage":"Focusable element with role \"{{role}}\" is hidden from the accessibility tree","axeEquivalents":["aria-hidden-focus"]}]};
+export default {
+  "interactiveRoles": ["button","link","textbox","combobox","listbox","menuitem","tab","checkbox","radio","switch","slider"],
+  "rules": [
+    {
+      "id": "cdp-missing-accessible-name",
+      "condition": "interactive-no-name",
+      "impact": "serious",
+      "tags": ["wcag2a","wcag412","cdp-check"],
+      "help": "Interactive elements must have an accessible name",
+      "helpUrl": "https://dequeuniversity.com/rules/axe/4.11/button-name",
+      "description": "Interactive element with role \"{{role}}\" has no accessible name",
+      "failureMessage": "Element with role \"{{role}}\" has no accessible name in the accessibility tree",
+      "axeEquivalents": ["button-name","link-name","input-name","aria-command-name"]
+    },
+    {
+      "id": "cdp-aria-hidden-focusable",
+      "condition": "hidden-focusable",
+      "impact": "serious",
+      "tags": ["wcag2a","wcag412","cdp-check"],
+      "help": "aria-hidden elements must not be focusable",
+      "helpUrl": "https://dequeuniversity.com/rules/axe/4.11/aria-hidden-focus",
+      "description": "Focusable element with role \"{{role}}\" is aria-hidden",
+      "failureMessage": "Focusable element with role \"{{role}}\" is hidden from the accessibility tree",
+      "axeEquivalents": ["aria-hidden-focus"]
+    },
+    {
+      "id": "cdp-autoplay-media",
+      "condition": "dom-eval",
+      "impact": "serious",
+      "tags": ["wcag2a","wcag142","wcag222","cdp-check"],
+      "help": "Media elements must not autoplay without user control",
+      "helpUrl": "https://www.w3.org/WAI/WCAG21/Understanding/audio-control.html",
+      "description": "Media element autoplays without user control (WCAG 1.4.2, 2.2.2)",
+      "failureMessage": "Media element has autoplay attribute without providing user controls to stop it",
+      "axeEquivalents": []
+    },
+    {
+      "id": "cdp-missing-main-landmark",
+      "condition": "dom-eval",
+      "impact": "moderate",
+      "tags": ["wcag2a","wcag131","best-practice","cdp-check"],
+      "help": "Page must have a main landmark",
+      "helpUrl": "https://dequeuniversity.com/rules/axe/4.11/landmark-one-main",
+      "description": "Page does not have a main landmark",
+      "failureMessage": "Document does not contain a <main> element or an element with role=\"main\"",
+      "axeEquivalents": ["landmark-one-main"]
+    },
+    {
+      "id": "cdp-missing-skip-link",
+      "condition": "dom-eval",
+      "impact": "moderate",
+      "tags": ["wcag2a","wcag241","best-practice","cdp-check"],
+      "help": "Page must have a skip navigation link",
+      "helpUrl": "https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks.html",
+      "description": "Page does not have a skip navigation link as the first focusable element",
+      "failureMessage": "No skip link found as first focusable element — keyboard users cannot bypass navigation",
+      "axeEquivalents": ["bypass"]
+    }
+  ]
+};

package/docs/api-reference.md

@@ -24,6 +24,7 @@
 - [Constants](#constants)
   - [VIEWPORT_PRESETS](#viewport_presets)
   - [DEFAULT_AI_SYSTEM_PROMPT](#default_ai_system_prompt)
+  - [PM_AI_SYSTEM_PROMPT](#pm_ai_system_prompt)
 
 ---
 
@@ -52,6 +53,7 @@ import {
   getKnowledge,
   VIEWPORT_PRESETS,
   DEFAULT_AI_SYSTEM_PROMPT,
+  PM_AI_SYSTEM_PROMPT,
 } from "@diegovelasquezweb/a11y-engine";
 ```
 
@@ -106,7 +108,7 @@ Returns a `ScanPayload` object consumed by all other functions.
 | `viewport` | `object` | `{ width: 1280, height: 800 }` | width: 320–2560, height: 320–2560 | Browser viewport dimensions in pixels |
 | `colorScheme` | `string` | `"light"` | `"light"` \| `"dark"` | Emulates `prefers-color-scheme` media query |
 | `engines` | `object` | all `true` | `{ axe?, cdp?, pa11y? }` | Which engines to run. At least one must be enabled |
-| `axeTags` | `string[]` | WCAG 2.x A+AA | See below | axe-core rule tag filter. Also determines pa11y standard |
+| `axeTags` | `string[]` | WCAG 2.x A+AA | See below | axe-core rule tag filter. Also determines pa11y standard. Add `"best-practice"` and/or `"ACT"` to include non-WCAG best practices and W3C ACT rules (opt-in, not included by default) |
 | `onlyRule` | `string` | — | axe rule ID | Run a single axe rule only (e.g. `"color-contrast"`) |
 | `ignoreFindings` | `string[]` | — | axe rule IDs | Suppress specific rules from output entirely |
 | `excludeSelectors` | `string[]` | — | CSS selectors | Skip elements matching these selectors during axe scan |
@@ -121,6 +123,9 @@ Returns a `ScanPayload` object consumed by all other functions.
 | `ai.githubToken` | `string` | — | GitHub PAT | Used to fetch source files from the repo for AI context |
 | `ai.model` | `string` | `"claude-haiku-4-5-20251001"` | Anthropic model ID | Claude model to use |
 | `ai.systemPrompt` | `string` | Built-in prompt | — | Overrides the default Claude system prompt for the entire scan |
+| `ai.audience` | `string` | `"dev"` | `"dev"` \| `"pm"` | Controls the AI enrichment tone. `"dev"` generates code-level fixes; `"pm"` generates business impact summaries |
+| `clearCache` | `boolean` | `false` | — | Clear browser cache before each page navigation via CDP `Network.clearBrowserCache`. Ensures fresh results on repeated scans of the same domain |
+| `serverMode` | `boolean` | `false` | — | Enable server/EC2/Docker Chrome launch flags: `--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`, `--disable-gpu`, `--no-zygote`, `--disable-accelerated-2d-canvas`. Use in CI, Docker, or EC2 environments |
 | `onProgress` | `function` | — | — | Callback fired at each pipeline step |
 
 **`axeTags` common values:**
@@ -134,10 +139,25 @@ Returns a `ScanPayload` object consumed by all other functions.
 | `wcag22a` | WCAG 2.2 Level A additions |
 | `wcag22aa` | WCAG 2.2 Level AA additions |
 | `wcag2aaa` | WCAG 2.0 Level AAA |
-| `best-practice` | Non-WCAG best practices |
+| `best-practice` | Non-WCAG best practices (opt-in) |
+| `ACT` | W3C Accessibility Conformance Testing rules (opt-in) |
 
 **Supported `framework` values:** `nextjs`, `gatsby`, `react`, `nuxt`, `vue`, `angular`, `astro`, `svelte`, `remix`, `shopify`, `wordpress`, `drupal`
 
+**CDP checks:**
+
+The `cdp` engine runs 5 checks split across two mechanisms:
+
+| Check ID | Mechanism | Impact | WCAG |
+| :--- | :--- | :--- | :--- |
+| `cdp-missing-accessible-name` | Accessibility tree | Serious | 4.1.2 A |
+| `cdp-aria-hidden-focusable` | Accessibility tree | Serious | 4.1.2 A |
+| `cdp-autoplay-media` | `page.evaluate()` | Serious | 1.4.2, 2.2.2 A |
+| `cdp-missing-main-landmark` | `page.evaluate()` | Moderate | 1.3.1 A |
+| `cdp-missing-skip-link` | `page.evaluate()` | Moderate | 2.4.1 A |
+
+All 5 checks have intelligence enrichment entries (fix description, fix code, framework notes, CMS notes).
+
 **`onProgress` callback:**
 
 ```ts
@@ -182,6 +202,9 @@ Returns: `Promise<ScanPayload>`
     },
     routes_scanned: number,              // How many pages were actually scanned
     discovery_method: string,            // "crawl" | "explicit"
+    passesCount: number,                 // Unique axe rules that passed (deduplicated across routes)
+    incompleteCount: number,             // Total axe incomplete results across routes (needs manual review)
+    inapplicableCount: number,           // Unique axe rules that were inapplicable (deduplicated across routes)
   },
   incomplete_findings?: RawFinding[],    // axe "incomplete" results (needs-review)
   patternFindings?: {                    // Only present if projectDir/repoUrl + !skipPatterns
@@ -308,6 +331,11 @@ Returns: `EnrichedFinding[]`
   guardrails: object | null,             // Guardrail metadata from the engine
   checkData: object | null,              // Raw check data from the engine
 
+  // PM audience fields (always present from intelligence DB)
+  pmSummary: string | null,              // One-line business impact for PMs
+  pmImpact: string | null,              // Business/legal/UX consequences
+  pmEffort: string | null,              // "quick-win" | "medium" | "strategic"
+
   // AI enrichment (only when ai.enabled ran)
   aiEnhanced?: boolean,                  // true when AI enriched this finding
   aiFixDescription?: string,             // Claude-generated fix explanation
@@ -651,6 +679,18 @@ Type: `string`
 
 ---
 
+### `PM_AI_SYSTEM_PROMPT`
+
+The system prompt used for PM-audience AI enrichment. Instructs Claude to generate business-oriented summaries instead of developer-focused fixes. Used automatically when `ai.audience` is `"pm"`.
+
+```ts
+import { PM_AI_SYSTEM_PROMPT } from "@diegovelasquezweb/a11y-engine";
+```
+
+Type: `string`
+
+---
+
 > **Note on `ai_enriched_findings` fast path**: When `getFindings()` receives a payload that contains `ai_enriched_findings` and no `screenshotUrlBuilder` option is provided, it returns `ai_enriched_findings` directly without re-normalizing the raw `findings` array. If a `screenshotUrlBuilder` is provided, normalization always runs so paths can be rewritten.
 
 ---

package/docs/architecture.md

@@ -82,7 +82,7 @@ flowchart LR
 
 | Module | Responsibility |
 | :--- | :--- |
-| `src/pipeline/dom-scanner.mjs` | Route discovery, engine execution (axe/CDP/pa11y), merge/dedup, progress updates, screenshots |
+| `src/pipeline/dom-scanner.mjs` | Route discovery, engine execution (axe/CDP/pa11y), merge/dedup, progress updates, screenshots. CDP checks use two mechanisms: CDP accessibility tree (missing accessible name, aria-hidden focusable) and `page.evaluate()` DOM inspection (autoplay media, missing main landmark, missing skip link). |
 | `src/enrichment/analyzer.mjs` | Rule enrichment, selector strategy, ownership hints, recommendations, scoring metadata |
 | `src/ai/enrich.mjs` | CLI subprocess that runs AI enrichment after the analyzer. Reads `ANTHROPIC_API_KEY` and `AI_SYSTEM_PROMPT` env vars. Non-fatal. |
 | `src/ai/claude.mjs` | Anthropic API client. Sends Critical/Serious findings to Claude and parses improved fix suggestions. Supports custom system prompt and repo source file context. |
@@ -120,6 +120,29 @@ Output shape:
 Core artifacts generated by the pipeline:
 
 - `progress.json`: step status — `page`, `axe`, `cdp`, `pa11y`, `merge`, `intelligence`, `repo` (remote package.json fetch), `patterns` (source pattern scan), `ai` (Claude enrichment)
+
+### CDP Check Mechanisms
+
+The CDP engine uses two distinct detection mechanisms within the same `runCdpChecks()` function:
+
+| Mechanism | Checks | Why |
+| :--- | :--- | :--- |
+| CDP Accessibility Tree (`Accessibility.getFullAXTree`) | `cdp-missing-accessible-name`, `cdp-aria-hidden-focusable` | Reads the computed accessibility tree — the actual view screen readers see. Required for role/name/state inspection. |
+| DOM evaluation (`page.evaluate()`) | `cdp-autoplay-media`, `cdp-missing-main-landmark`, `cdp-missing-skip-link` | Inspects HTML attributes and DOM structure that are not reflected in the accessibility tree. `autoplay` is a media attribute; landmark and skip link presence are structural checks. |
+
+### Engine Execution Model
+
+Within each route, the three engines run with optimized parallelism:
+
+```
+┌─ axe-core (navigates + analyzes page) ──────────────────────────────┐
+│   └─ CDP checks (reads same loaded page — sequential after axe)      ├──→ merge
+└─ pa11y (own shared Puppeteer browser, independent) ─────────────────┘
+```
+
+- **axe → CDP**: Sequential. CDP depends on axe's page navigation. Both share the same Playwright tab.
+- **pa11y**: Starts in parallel with axe. Uses a single shared Puppeteer browser instance (launched once per scan, reused for all routes). This eliminates the Chrome cold-start overhead (1-3s) that would occur if pa11y launched its own browser per route.
+- **Route batching**: Up to 3 routes are scanned in parallel via Playwright tabs. Each route runs its own axe→CDP→(merge with pa11y) sequence.
 - `a11y-scan-results.json`: merged runtime scan output per route
 - `a11y-findings.json`: enriched findings payload used by reports and API consumers
 

package/docs/intelligence.md

@@ -51,7 +51,7 @@ flowchart TD
 
 ## Intelligence Database
 
-The engine ships a bundled intelligence database at `assets/remediation/intelligence.mjs`. This contains per-rule entries keyed by axe rule ID (e.g. `color-contrast`, `image-alt`).
+The engine ships a bundled intelligence database at `assets/remediation/intelligence.mjs`. This contains per-rule entries keyed by axe rule ID (e.g. `color-contrast`, `image-alt`) and CDP check IDs (e.g. `cdp-autoplay-media`, `cdp-missing-main-landmark`, `cdp-missing-skip-link`).
 
 Each rule entry can include:
 
@@ -68,6 +68,9 @@ Each rule entry can include:
 | `cms_notes` | CMS-specific fix guidance |
 | `preferred_relationship_checks` | axe check IDs to prioritize for relationship hints |
 | `guardrails` / `guardrails_overrides` | Must/must-not/verify constraints for automated fixes |
+| `pm.summary` | One-line business impact for PM audience (e.g. "Buttons without labels block screen reader users from key actions") |
+| `pm.impact` | Business/legal/UX consequences for non-technical stakeholders |
+| `pm.effort` | Effort classification: `quick-win`, `medium`, or `strategic` |
 
 When a framework is detected (e.g. `nextjs`), only the relevant framework notes are included in the output. React-based frameworks (`nextjs`, `gatsby`) resolve to `react` notes.
 
@@ -250,11 +253,21 @@ AI enrichment runs automatically when `ANTHROPIC_API_KEY` is present in the envi
 
 The default system prompt instructs Claude to go beyond the generic fix: explain why the issue matters for users, reference the specific selector and violation data, and provide a more complete code example than the engine's default. The prompt can be overridden per-scan via the `AI_SYSTEM_PROMPT` env var or `options.ai.systemPrompt` in the programmatic API.
 
+### PM audience mode
+
+When `ai.audience` is set to `"pm"`, the AI enrichment uses a PM-specific system prompt that generates business-oriented guidance instead of developer-focused fixes. The PM prompt instructs Claude to produce:
+
+- `pmSummary` — one-line business impact in plain language
+- `pmImpact` — 2-3 sentences on legal/compliance/UX consequences
+- `pmEffort` — `quick-win`, `medium`, or `strategic` with time estimate
+
+These AI-generated PM fields override the static PM fields from the intelligence database for Critical and Serious findings, similar to how `fixDescription` overrides the static fix for dev audience.
+
 ## Assets Reference
 
 | Asset | Used by | Purpose |
 | :--- | :--- | :--- |
-| `remediation/intelligence.mjs` | analyzer | Per-rule fix descriptions, code, guardrails, framework notes |
+| `remediation/intelligence.mjs` | analyzer | Per-rule fix descriptions, code, guardrails, framework notes. Covers 101 axe-core rules + 3 CDP-specific checks (`cdp-autoplay-media`, `cdp-missing-main-landmark`, `cdp-missing-skip-link`) |
 | `remediation/axe-check-maps.mjs` | analyzer | Failure mode and relationship hint mappings from axe check IDs |
 | `remediation/guardrails.mjs` | analyzer | Shared guardrail constraints for safe automated fixes |
 | `remediation/source-boundaries.mjs` | analyzer, source-scanner | Framework-specific source directory scoping |

package/docs/outputs.md

@@ -89,7 +89,8 @@ Merged results from all three engines (axe-core + CDP + pa11y) per route. Writte
       "url": "https://example.com/",
       "violations": [...],
       "incomplete": [...],
-      "passes": [...]
+      "passes": ["aria-hidden-focus", "document-title", ...],
+      "inapplicable": ["video-caption", "audio-caption", ...]
     }
   ]
 }
@@ -128,6 +129,9 @@ The primary enriched data artifact. Written by `src/enrichment/analyzer.mjs`. Th
 | `recommendations` | `object[]` | Grouped fix recommendations by component |
 | `testingMethodology` | `object` | Scan scope and methodology summary |
 | `fpFiltered` | `number` | Count of findings filtered as likely false positives |
+| `passesCount` | `number` | Unique axe-core rules that passed (deduplicated across all scanned routes) |
+| `incompleteCount` | `number` | Total axe-core incomplete results across all routes — items that need manual review |
+| `inapplicableCount` | `number` | Unique axe-core rules that were inapplicable (deduplicated across all scanned routes) |
 | `deduplicatedCount` | `number` | Count of duplicate findings removed |
 
 ### `findings` — per-finding fields
@@ -181,6 +185,9 @@ The primary enriched data artifact. Written by `src/enrichment/analyzer.mjs`. Th
 | `verification_command_fallback` | `string\|null` | Fallback verify command |
 | `pages_affected` | `number\|null` | Number of pages with this violation |
 | `affected_urls` | `string[]\|null` | All URLs where this violation appears |
+| `pm_summary` | `string\|null` | One-line business impact for PM audience. Populated from the intelligence database for all findings. |
+| `pm_impact` | `string\|null` | Business/legal/UX consequences for non-technical stakeholders. |
+| `pm_effort` | `string\|null` | Effort classification: `quick-win`, `medium`, or `strategic`. |
 | `aiEnhanced` | `boolean` | `true` when Claude improved the fix for this finding. Only present on AI-enriched findings. |
 | `ai_fix_description` | `string\|null` | Claude-generated fix description. More specific than `fix_description` — references the actual selector, colors, and violation data. Only present when `aiEnhanced` is `true`. |
 | `ai_fix_code` | `string\|null` | Claude-generated code snippet in the correct framework syntax. Separate from the engine's `fix_code`. Only present when `aiEnhanced` is `true`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegovelasquezweb/a11y-engine",
-  "version": "0.10.2",
+  "version": "0.11.1",
   "description": "WCAG 2.2 accessibility audit engine — scanner, analyzer, and report builders",
   "type": "module",
   "license": "MIT",

package/src/ai/claude.mjs

@@ -41,6 +41,21 @@ Rules:
 - If the violation data contains specific values (colors, ratios, labels), use them in your response
 - Respond in JSON only — no markdown, no explanation outside the JSON structure`;
 
+export const PM_AI_SYSTEM_PROMPT = `You are an accessibility compliance advisor for product managers and non-technical stakeholders.
+
+Your task is to provide a business-oriented summary for each accessibility finding — something a PM can use to prioritize, communicate to stakeholders, and plan sprints.
+
+For each finding, provide:
+1. pmSummary: A single sentence describing who is affected and what they cannot do. Use plain language, no technical jargon.
+2. pmImpact: 2-3 sentences on business consequences: legal/compliance risk, user segments blocked, effect on conversions/engagement/SEO. Be specific to the violation.
+3. pmEffort: One of "quick-win", "medium", or "strategic" with a brief time estimate (e.g., "quick-win — under 1 hour per instance").
+
+Rules:
+- Write for a non-technical audience — no code, no selectors, no ARIA terminology
+- Focus on users affected, business risk, and prioritization
+- Reference the actual violation data (title, severity, affected users) to be specific
+- Respond in JSON only — no markdown, no explanation outside the JSON structure`;
+
 function buildSystemPrompt(context) {
   const { framework, cms, uiLibraries } = context.stack || {};
 
@@ -98,6 +113,37 @@ function buildUserMessage(findings, sourceFiles) {
   return message;
 }
 
+/**
+ * Builds the user message for PM audience.
+ * @param {EnrichedFinding[]} findings
+ * @returns {string}
+ */
+function buildPmUserMessage(findings) {
+  const items = findings.map((f, i) => ({
+    index: i,
+    title: f.title,
+    severity: f.severity,
+    wcag: f.wcag,
+    impactedUsers: f.impactedUsers,
+    currentPmSummary: f.pmSummary,
+    currentPmImpact: f.pmImpact,
+    totalInstances: f.totalInstances,
+    pagesAffected: f.pagesAffected,
+  }));
+
+  let message = `Improve the PM-facing guidance for these ${findings.length} accessibility finding(s).\n\n`;
+  message += `FINDINGS:\n${JSON.stringify(items, null, 2)}\n`;
+  message += `\nRespond with a JSON array where each item has:\n`;
+  message += `{
+  "index": <number>,
+  "pmSummary": "<one-line business impact>",
+  "pmImpact": "<2-3 sentences on business/legal/UX consequences>",
+  "pmEffort": "<quick-win|medium|strategic with time estimate>"
+}`;
+
+  return message;
+}
+
 /**
  * Calls the Claude API with the given messages.
  * @param {string} apiKey
@@ -266,6 +312,7 @@ export async function enrichWithAI(findings, context = {}, options = {}) {
   if (!enabled) return findings;
 
   const model = options.model || DEFAULT_MODEL;
+  const audience = options.audience || "dev";
   const customSystemPrompt = options.systemPrompt || null;
 
   // Only enrich Critical and Serious findings, cap total
@@ -281,11 +328,16 @@ export async function enrichWithAI(findings, context = {}, options = {}) {
       ? await fetchSourceFilesForFindings(targets, context.repoUrl, options.githubToken)
       : {};
 
-    const systemPrompt = customSystemPrompt || buildSystemPrompt({
-      stack: context.stack,
-      hasSourceCode: Object.keys(sourceFiles).length > 0,
-    });
-    const userMessage = buildUserMessage(targets, sourceFiles);
+    const isPm = audience === "pm";
+    const systemPrompt = customSystemPrompt || (isPm
+      ? PM_AI_SYSTEM_PROMPT
+      : buildSystemPrompt({
+          stack: context.stack,
+          hasSourceCode: Object.keys(sourceFiles).length > 0,
+        }));
+    const userMessage = isPm
+      ? buildPmUserMessage(targets)
+      : buildUserMessage(targets, sourceFiles);
 
     const responseText = await callClaude(options.apiKey, model, systemPrompt, userMessage);
 
@@ -311,6 +363,15 @@ export async function enrichWithAI(findings, context = {}, options = {}) {
       const imp = improvementMap.get(targetIdx);
       if (!imp) return finding;
 
+      if (isPm) {
+        return {
+          ...finding,
+          pmSummary: imp.pmSummary || finding.pmSummary,
+          pmImpact: imp.pmImpact || finding.pmImpact,
+          pmEffort: imp.pmEffort || finding.pmEffort,
+        };
+      }
+
       return {
         ...finding,
         fixDescription: imp.fixDescription || finding.fixDescription,

package/src/enrichment/analyzer.mjs

@@ -639,6 +639,29 @@ function computeOverallAssessment(findings) {
   return "Pass";
 }
 
+/**
+ * Computes pass/incomplete/inapplicable counts across all scanned routes.
+ * @param {Object[]} routes - Raw scan routes.
+ * @returns {{ passesCount: number, incompleteCount: number, inapplicableCount: number }}
+ */
+function computeAxeCounts(routes) {
+  const passedRules = new Set();
+  const inapplicableRules = new Set();
+  let incompleteCount = 0;
+
+  for (const route of routes) {
+    for (const ruleId of route.passes || []) passedRules.add(ruleId);
+    for (const ruleId of route.inapplicable || []) inapplicableRules.add(ruleId);
+    incompleteCount += (route.incomplete || []).length;
+  }
+
+  return {
+    passesCount: passedRules.size,
+    incompleteCount,
+    inapplicableCount: inapplicableRules.size,
+  };
+}
+
 /**
  * Aggregates WCAG 2.2 AA criteria that passed across all scanned routes.
  * @param {Object[]} routes - Raw scan routes with a passes array of rule IDs.
@@ -907,6 +930,9 @@ function buildFindings(inputPayload, cliArgs) {
           needs_verification: !!v._fromIncomplete,
           verification_command: `pnpm a11y --base-url ${route.url} --routes ${route.path} --only-rule ${v.id} --max-routes 1`,
           verification_command_fallback: `node scripts/audit.mjs --base-url ${route.url} --routes ${route.path} --only-rule ${v.id} --max-routes 1`,
+          pm_summary: ruleInfo.pm?.summary ?? null,
+          pm_impact: ruleInfo.pm?.impact ?? null,
+          pm_effort: ruleInfo.pm?.effort ?? null,
         });
       }
     }
@@ -1044,6 +1070,7 @@ export function runAnalyzer(scanPayload, options = {}) {
   const recommendations = computeRecommendations(dedupedFindings);
   const testingMethodology = computeTestingMethodology(scanPayload);
   const incompleteFindings = collectIncompleteFindings(scanPayload.routes || []);
+  const axeCounts = computeAxeCounts(scanPayload.routes || []);
   if (incompleteFindings.length > 0)
     log.info(`${incompleteFindings.length} incomplete finding(s) require manual review.`);
 
@@ -1060,6 +1087,9 @@ export function runAnalyzer(scanPayload, options = {}) {
       testingMethodology,
       fpFiltered: fpRemovedCount,
       deduplicatedCount,
+      passesCount: axeCounts.passesCount,
+      incompleteCount: axeCounts.incompleteCount,
+      inapplicableCount: axeCounts.inapplicableCount,
     },
   };
 

package/src/index.d.mts

@@ -52,6 +52,9 @@ export interface Finding {
   pages_affected?: number | null;
   affected_urls?: string[] | null;
   needs_verification?: boolean;
+  pm_summary: string | null;
+  pm_impact: string | null;
+  pm_effort: string | null;
 }
 
 export interface EnrichedFinding {
@@ -104,6 +107,9 @@ export interface EnrichedFinding {
   pagesAffected: number | null;
   affectedUrls: string[] | null;
   needsVerification?: boolean;
+  pmSummary: string | null;
+  pmImpact: string | null;
+  pmEffort: string | null;
 }
 
 export interface SeverityTotals {
@@ -141,9 +147,32 @@ export interface AuditSummary {
 
 
 
+export interface ScanMetadata {
+  target_url?: string;
+  scanned_at?: string;
+  engines?: { axe: boolean; cdp: boolean; pa11y: boolean };
+  projectContext?: { framework: string | null; cms: string | null; uiLibraries: string[] };
+  routes_scanned?: number;
+  discovery_method?: string;
+  overallAssessment?: Record<string, unknown>;
+  passedCriteria?: string[];
+  outOfScope?: Record<string, unknown>;
+  recommendations?: unknown[];
+  testingMethodology?: Record<string, unknown>;
+  fpFiltered?: number;
+  deduplicatedCount?: number;
+  /** Total number of unique axe-core rules that passed (deduplicated across all scanned routes). */
+  passesCount?: number;
+  /** Total number of axe-core incomplete results across all scanned routes (needs manual review). */
+  incompleteCount?: number;
+  /** Total number of unique axe-core rules that were inapplicable (deduplicated across all scanned routes). */
+  inapplicableCount?: number;
+  [key: string]: unknown;
+}
+
 export interface ScanPayload {
   findings: Finding[] | Record<string, unknown>[];
-  metadata?: Record<string, unknown>;
+  metadata?: ScanMetadata;
   incomplete_findings?: unknown[];
 }
 
@@ -391,7 +420,31 @@ export interface RunAuditOptions {
   waitUntil?: string;
   colorScheme?: string;
   viewport?: { width: number; height: number };
+  /**
+   * axe-core rule tag filter. Also determines the pa11y standard used.
+   * Default: `["wcag2a","wcag2aa","wcag21a","wcag21aa","wcag22a","wcag22aa"]`
+   *
+   * Optional opt-in tags (not included by default):
+   * - `"best-practice"` — non-WCAG best practices (duplicate IDs, landmark structure, etc.)
+   * - `"ACT"` — W3C Accessibility Conformance Testing rules
+   * - `"wcag2aaa"` / `"wcag21aaa"` — WCAG Level AAA rules
+   */
   axeTags?: string[];
+  /**
+   * Clear browser cache before each page navigation.
+   * Ensures fresh scan results when scanning the same domain multiple times.
+   * Uses CDP `Network.clearBrowserCache` + `Network.setCacheDisabled`.
+   * Default: `false`
+   */
+  clearCache?: boolean;
+  /**
+   * Enable server/EC2/Docker-optimized Chrome launch flags.
+   * Adds: `--no-sandbox`, `--disable-setuid-sandbox`, `--disable-dev-shm-usage`,
+   * `--disable-gpu`, `--no-zygote`, `--disable-accelerated-2d-canvas`.
+   * Use this when running in CI, Docker, or EC2 environments.
+   * Default: `false`
+   */
+  serverMode?: boolean;
   onlyRule?: string;
   excludeSelectors?: string[];
   ignoreFindings?: string[];
@@ -457,6 +510,7 @@ export function getSourcePatterns(
 export function getKnowledge(options?: KnowledgeOptions): EngineKnowledge;
 
 export const DEFAULT_AI_SYSTEM_PROMPT: string;
+export const PM_AI_SYSTEM_PROMPT: string;
 
 export interface ViewportPreset {
   label: string;
@@ -472,4 +526,5 @@ export interface AiOptions {
   githubToken?: string;
   model?: string;
   systemPrompt?: string;
+  audience?: "pm" | "dev";
 }

package/src/index.mjs

@@ -5,7 +5,7 @@
  */
 
 import { ASSET_PATHS, loadAssetJson } from "./core/asset-loader.mjs";
-export { DEFAULT_AI_SYSTEM_PROMPT } from "./ai/claude.mjs";
+export { DEFAULT_AI_SYSTEM_PROMPT, PM_AI_SYSTEM_PROMPT } from "./ai/claude.mjs";
 
 // Lazy-loaded asset cache
 
@@ -162,6 +162,9 @@ function normalizeSingleFinding(item, index, screenshotUrlBuilder) {
     pages_affected: typeof item.pages_affected === "number" ? item.pages_affected : null,
     affected_urls: Array.isArray(item.affected_urls) ? item.affected_urls : null,
     needs_verification: Boolean(item.needs_verification),
+    pm_summary: strOrNull(item.pm_summary),
+    pm_impact: strOrNull(item.pm_impact),
+    pm_effort: strOrNull(item.pm_effort),
   };
 }
 
@@ -249,6 +252,9 @@ export function getFindings(input, options = {}) {
       pagesAffected: finding.pages_affected,
       affectedUrls: finding.affected_urls,
       needsVerification: finding.needs_verification,
+      pmSummary: finding.pm_summary ?? null,
+      pmImpact: finding.pm_impact ?? null,
+      pmEffort: finding.pm_effort ?? null,
     };
 
     // Enrich from intelligence if no fix data exists yet
@@ -688,6 +694,8 @@ export async function runAudit(options) {
       projectDir: options.projectDir,
       remotePackageJson,
       engines,
+      clearCache: options.clearCache ?? false,
+      serverMode: options.serverMode ?? false,
     },
     { onProgress },
   );
@@ -793,6 +801,7 @@ export async function runAudit(options) {
           apiKey: aiOptions.apiKey,
           githubToken: aiOptions.githubToken || options.githubToken,
           model: aiOptions.model,
+          audience: aiOptions.audience || "dev",
         }
       );