@appfire-ux/audit-agent 0.20260708.4 → 0.20260709.0

package/README.md

@@ -9,67 +9,49 @@ Agents:
 
 - **ux-auditor** (`/ux-audit`) — guideline-compliance UX audit: design tokens, spacing/typography, accessibility, UX writing, messaging patterns, persona fit.
 - **ui-auditor** (`/ui-audit`) — UI & usability audit from a UI Designer's perspective: cross-screen consistency, layout & visual hierarchy, information architecture, navigation, interaction design, forms, data-dense views, responsiveness. Screenshot-driven (browser MCP or bundled Playwright fallback).
-- **a11y-auditor** (`/a11y-audit`) — deep accessibility audit per the Appfire VPAT Compliance Protocol: WCAG 2.2 A/AA, automated axe-core scans of the running app (Baseline Accessibility Score), static four-principles code audit, manual validation register, evidence-gap register, and JSON datapoints that feed the "AI Agent: VPAT Document" (Confluence, CRUX) to draft the Accessibility Conformance Report. Strict no-over-claiming language.
+- **a11y-auditor** (`/a11y-audit`) — deep accessibility audit: WCAG 2.2 A/AA, axe-core scans, static four-principles code audit, JSON datapoints for VPAT. Strict no-over-claiming language.
 
-## Install
+**VPAT/ACR drafting** is a separate package: [`@appfire-ux/vpat-agent`](../appfire-ux-vpat-agent/) — install for `/vpat-audit` (full VPAT pipeline with mandatory UI URL).
 
-In the repo you want to audit:
+## Install
 
 ```bash
 npm install -D @appfire-ux/audit-agent
 ```
 
-The postinstall script copies the agent and command into `<repo>/.claude/`. Done — open Claude Code and run:
-
-```
-/full-audit   # all audits in parallel (recommended)
-/ux-audit     # compliance only
-/ui-audit     # UI & usability only
-/a11y-audit   # accessibility / VPAT readiness only
-```
-
-Once, for all repos on your machine:
+For VPAT/ACR in the same repo:
 
 ```bash
-npx @appfire-ux/audit-agent --global   # installs into ~/.claude/
+npm install -D @appfire-ux/vpat-agent @appfire-ux/guidelines
+npx @appfire-ux/vpat-agent
 ```
 
-## Update (manual, optional)
+Open Claude Code:
 
-Phase 0 on every `/ux-audit`, `/ui-audit`, `/a11y-audit`, or `/full-audit` run already calls `npm update` + `@latest` for both packages. Use this only when you want to refresh **without** running an audit:
-
-```bash
-npm update @appfire-ux/audit-agent @appfire-ux/guidelines
-npx @appfire-ux/audit-agent
-npx @appfire-ux/guidelines
+```
+/full-audit   # UX + UI + A11Y in parallel; VPAT post-sequence via @appfire-ux/vpat-agent (default)
+/vpat-audit --url https://localhost:5173   # VPAT-only (requires @appfire-ux/vpat-agent)
 ```
 
 ## What gets installed
 
 | File | Purpose |
-|---|---|
-| `.claude/agents/ux-auditor.md` | Guideline-compliance audit → MD + HTML + `assets/*.png` (Confluence-ready) |
-| `.claude/commands/ux-audit.md` | `/ux-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
-| `.claude/agents/ui-auditor.md` | UI & usability audit → same deliverable format |
-| `.claude/commands/ui-audit.md` | `/ui-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod]` |
-| `.claude/agents/a11y-auditor.md` | Accessibility/VPAT audit → MD + HTML + JSON datapoints + `axe-results/` |
-| `.claude/commands/a11y-audit.md` | `/a11y-audit [scope] [--static-only] [--lang pl] [--out <path>] [--prod] [--routes …]` |
-| `.claude/agents/vpat-repo-auditor.md` | VPAT/ACR evidence-gap pre-audit → `VPAT-REPO-AUDIT-*.md` + `.json` |
-| `.claude/agents/vpat-acr-drafter.md` | ACR draft from evidence package → `ACR-DRAFT-*.md` |
-| `.claude/commands/full-audit.md` | `/full-audit` — parallel UX/UI/A11Y audit + default VPAT post-sequence (`--with-vpat`) |
-| `scripts/ux-audit-capture.mjs` | Playwright screenshot fallback (`--widths 1440,768`) |
-| `scripts/a11y-audit-scan.mjs` | Playwright + axe-core scanner → per-route JSON + Baseline Score |
-| `scripts/build-html-reports.mjs` | MD → Confluence-ready HTML with local `assets/` gallery |
-
-The audits complement each other. Every run produces **Markdown + HTML + PNG assets** under `docs/audits/` (STOP & ASK on auth walls; no base64). Use `/full-audit` for all agents in parallel. The a11y audit additionally produces machine-readable datapoints (`A11Y-AUDIT-<date>.json` + `axe-results/*.json`) for the VPAT/ACR drafting workflow.
+|------|---------|
+| `.claude/agents/ux-auditor.md` | Guideline-compliance audit |
+| `.claude/commands/ux-audit.md` | `/ux-audit` |
+| `.claude/agents/ui-auditor.md` | UI & usability audit |
+| `.claude/commands/ui-audit.md` | `/ui-audit` |
+| `.claude/agents/a11y-auditor.md` | Accessibility audit → JSON for VPAT |
+| `.claude/commands/a11y-audit.md` | `/a11y-audit` |
+| `.claude/commands/full-audit.md` | `/full-audit` parallel orchestration |
+| `scripts/ux-audit-capture.mjs` | Playwright screenshot fallback |
+| `scripts/a11y-audit-scan.mjs` | Playwright + axe-core scanner |
+| `scripts/build-html-reports.mjs` | MD → Confluence-ready HTML |
+
+VPAT agents, CRUX template, and `/vpat-audit` live in **`@appfire-ux/vpat-agent`**.
 
 ## Publishing (maintainers)
 
-**CI (preferred):** pushes to `main` that touch `appfire-ux-audit-agent/**` or the canonical agent/command files in `.claude/` (`ux-auditor.md`, `ux-audit.md`, `ui-auditor.md`, `ui-audit.md`, `a11y-auditor.md`, `a11y-audit.md`, `full-audit.md`) run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml). The workflow assembles the package (syncing templates from `.claude/`), bumps a date-based version (`0.YYYYMMDD.PATCH`), and publishes `@appfire-ux/audit-agent` using the `NPM_TOKEN` secret — same pattern as `@appfire-ux/guidelines` and `@appfire-ux/fonts`.
+Pushes to `main` touching `appfire-ux-audit-agent/**` or canonical UX/UI/A11Y files run [`.github/workflows/publish-audit-agent.yml`](../.github/workflows/publish-audit-agent.yml).
 
-**Manual:**
-
-```bash
-cd appfire-ux-audit-agent
-npm publish --access public   # requires publish rights to the @appfire-ux scope
-```
+VPAT package: [`.github/workflows/publish-vpat-agent.yml`](../.github/workflows/publish-vpat-agent.yml).

package/bin/install.js

@@ -72,8 +72,10 @@ console.log('Usage (in Claude Code, inside your repo):');
 console.log('  /full-audit               all audits in parallel (recommended; --agents ux,ui,a11y)');
 console.log('  /ux-audit                 guideline-compliance UX audit (tokens, a11y, content, messaging)');
 console.log('  /ui-audit                 UI & usability audit (consistency, IA, interaction design)');
-console.log('  /a11y-audit               accessibility audit: WCAG 2.2 + axe-core scan, feeds VPAT/ACR');
-console.log('  All accept: [scope-path] [--static-only] [--lang pl]');
+console.log('  /a11y-audit               accessibility audit (feeds @appfire-ux/vpat-agent for VPAT/ACR)');
+console.log('  All accept: [scope-path] [--url <ui-url>] [--static-only] [--lang pl]');
 console.log('  /full-audit also: [--out-dir <path>]   others: [--out <path>]');
 console.log('');
+console.log('VPAT/ACR: npm install -D @appfire-ux/vpat-agent && /vpat-audit --url <ui-url>');
+console.log('');
 console.log('Tip: run "npx appfire-ux-audit-agent --global" to install into ~/.claude for all repos.');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260708.4",
-  "description": "Claude Code audit agents for Appfire apps — ux-auditor (/ux-audit), ui-auditor (/ui-audit), a11y-auditor (/a11y-audit: WCAG 2.2 + axe-core scan feeding the Appfire VPAT/ACR process), /full-audit parallel orchestration. Confluence-ready MD+HTML+PNG output, runtime capture & scan scripts.",
+  "version": "0.20260709.0",
+  "description": "Claude Code audit agents for Appfire apps — ux-auditor (/ux-audit), ui-auditor (/ui-audit), a11y-auditor (/a11y-audit), /full-audit parallel orchestration. VPAT/ACR drafting: install @appfire-ux/vpat-agent separately.",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -15,7 +15,6 @@
     "accessibility",
     "a11y",
     "wcag",
-    "vpat",
     "claude-code",
     "atlassian",
     "design-system"

package/templates/agents/a11y-auditor.md

@@ -159,7 +159,7 @@ Write `docs/audits/a11y-audit/A11Y-AUDIT-<YYYY-MM-DD>[-prod].md` (honor `--out`)
 12. **Missing routes table** — route, status (`SCANNED`/`FAILED`/`BLOCKED`), blocker, next action.
 13. **Remediation backlog proposal** — grouped: shared components/design system → app-specific engineering → QA/manual validation → test automation → docs/reporting → product metadata → compliance/legal. Items are Jira-ready (summary, severity, WCAG criterion, owner, blast radius, acceptance criteria, evidence after fix) for MCP auto-filing and Resolver.
 14. **Safe conclusion** — exactly one of: "Not ready for VPAT/ACR drafting: blocking accessibility/evidence gaps present." / "Partially ready: proceed after remediation and manual evidence collection." / "Ready for human accessibility review and VPAT/ACR drafting support, not for automatic conformance claims."
-15. **Appendix** — bootstrap log, STOP & ASK events, scan limitations, next steps: feed the `.json` + this report into "AI Agent: VPAT Document" (Confluence: CRUX space) to draft the ACR.
+15. **Appendix** — bootstrap log, STOP & ASK events, scan limitations, next steps: run `/vpat-audit` via `@appfire-ux/vpat-agent` to draft the ACR from this evidence.
 
 **JSON datapoints file** — write `A11Y-AUDIT-<date>[-prod].json`:
 ```json

package/templates/commands/a11y-audit.md

@@ -1,22 +1,27 @@
 ---
-description: Comprehensive accessibility audit (WCAG 2.2 A/AA, axe-core scan) feeding the Appfire VPAT/ACR process
-argument-hint: [scope-path] [--static-only] [--lang pl|en] [--out <path>] [--prod] [--routes /,/foo]
+description: Comprehensive accessibility audit (WCAG 2.2 A/AA, axe-core scan) — feeds @appfire-ux/vpat-agent for ACR drafting
+argument-hint: [--url <base-url>] [scope-path] [--static-only] [--lang pl|en] [--out <path>] [--prod] [--routes /,/foo]
 ---
 
-Use the **a11y-auditor** agent to run a full accessibility & VPAT-readiness audit of this repository.
+Use the **a11y-auditor** agent to run a full accessibility audit of this repository.
 
 Arguments passed by the user: `$ARGUMENTS`
 
-Interpretation:
-- A path argument limits the audit scope (default: whole repo, baseline key screens prioritized).
-- `--static-only` — skip Phase 3 (axe scan + capture); warn the user: without runtime scanning most criteria become NEEDS_MANUAL_REVIEW and the report is much weaker as VPAT evidence.
-- `--lang pl` — report in Polish (default: English). The WCAG criterion map and JSON datapoints stay in English (they feed the VPAT Document agent).
-- `--out <path>` — report MD path (default: `docs/audits/a11y-audit/A11Y-AUDIT-<date>[-prod].md`).
-- `--prod` — append `-prod` to filenames (auditing production/staging URL).
-- `--routes` — explicit route list for the axe scan (default: from the surface map).
+## UI URL (strongly recommended for VPAT)
+
+For VPAT/ACR evidence, a **running UI URL** is required. If the user did not pass `--url <base-url>`, **ask before scanning**:
 
-Deliverables: **MD + HTML + JSON datapoints + axe-results/*.json + PNG in `assets/`** (Confluence-ready). STOP & ASK on auth/login walls before faking runtime evidence. Generate HTML via `build-html-reports.mjs` after the MD report.
+> Podaj link do działającego środowiska UI (`--url`), np. dev server lub instancja Atlassian. Bez skanu UI VPAT będzie oparty głównie na kodzie.
+
+Interpretation:
+- `--url <base-url>` — running UI root for axe scan and screenshots
+- A path argument limits the audit scope (default: whole repo, baseline key screens prioritized)
+- `--static-only` — skip Phase 3 (axe scan + capture); warn: without runtime scanning most criteria become NEEDS_MANUAL_REVIEW and VPAT evidence is weak
+- `--lang pl` — report in Polish (default: English). WCAG criterion map and JSON stay in English
+- `--out <path>` — report MD path (default: `docs/audits/a11y-audit/A11Y-AUDIT-<date>[-prod].md`)
+- `--prod` — append `-prod` to filenames
+- `--routes` — explicit route list for the axe scan (default: from the surface map)
 
-Launch the agent with these parameters and let it follow its full methodology: Phase 0 toolchain refresh (audit-agent, guidelines, playwright + axe-core), early axe-core scan, static four-principles audit, VPAT readiness assessment, and Phase 7 self-verification with strict no-over-claiming language.
+Deliverables: **MD + HTML + JSON datapoints + axe-results/*.json + PNG in `assets/`**. STOP & ASK on auth/login walls. Generate HTML via `build-html-reports.mjs` after the MD report.
 
-When it finishes, relay: MD + HTML + JSON paths, Baseline Accessibility Score, finding counts by severity (BLOCKER/MAJOR/MINOR/INFO), top 3 blockers, safe conclusion, scan coverage, Limitations — and remind the user that the `.json` + report feed the "AI Agent: VPAT Document" (Confluence, CRUX space) to draft the ACR.
+When it finishes, relay: MD + HTML + JSON paths, Baseline Accessibility Score, finding counts, scan URL, scan coverage, Limitations — and point to `/vpat-audit` or `npm install -D @appfire-ux/vpat-agent` for the full VPAT pipeline (repo audit + ACR draft).

package/templates/commands/full-audit.md

@@ -17,9 +17,14 @@ Arguments passed by the user: `$ARGUMENTS`
 - `--lang pl|en` — report language for all agents (default: English; a11y JSON/criterion map stays English).
 - `--out-dir <path>` — parent folder for outputs (default: `docs/audits`).
 - `--prod` — append `-prod` to report filenames (auditing production/staging URL).
+- `--url <base-url>` — running UI environment for axe scans and screenshots (dev/staging/prod). **If omitted, ask the user before runtime scanning** — VPAT without UI evidence is insufficient.
 
 Date slug: `YYYY-MM-DD` + optional `-prod` suffix.
 
+## UI URL gate (before parallel agents)
+
+If no `--url` was provided and `--static-only` was not explicitly confirmed, **STOP and ask** for a reachable UI link before launching agents that need runtime evidence (especially a11y). See `/vpat-audit` Step 0 for the exact prompt text.
+
 ## Coverage contract (mandatory)
 
 Default policy: do not finalize `/full-audit` without 100% route coverage for all requested agents.
@@ -260,7 +265,19 @@ Before writing AUDIT-SUMMARY:
 
 ## Step 4 — VPAT post-sequence (enabled by default)
 
-Run this by default. Skip only if user explicitly disables VPAT sequence for this run. This is strictly sequential:
+Run this by default. Skip only if user explicitly disables VPAT sequence for this run.
+
+**Bootstrap VPAT package first:**
+```bash
+npm update @appfire-ux/vpat-agent
+npx @appfire-ux/vpat-agent
+```
+
+This installs `vpat-repo-auditor`, `vpat-acr-drafter`, and the CRUX template into `.claude/`.
+
+**UI URL requirement:** If the parallel a11y audit ran without a verified UI scan URL, STOP before VPAT drafting and ask the user for `--url <base-url>`, then re-run or supplement a11y evidence. VPAT without UI scan is code-only and insufficient for a credible ACR.
+
+This step is strictly sequential:
 1. `vpat-repo-auditor` runs first, consuming:
    - `a11y-audit/A11Y-AUDIT-<date>[-prod].md`
    - `a11y-audit/A11Y-AUDIT-<date>[-prod].json`
@@ -276,8 +293,8 @@ Run this by default. Skip only if user explicitly disables VPAT sequence for thi
 VPAT sequence rules:
 - Assume a11y audit already exists; if missing, stop and instruct to run/repair a11y audit first.
 - Both VPAT agents are read-only and must never over-claim conformance.
-- `vpat-acr-drafter` output must be only the ACR document body and start with:
-  `Appfire Accessibility Conformance Report`
+- `vpat-acr-drafter` output must be only the ACR document body, built from the Appfire CRUX VPAT template (`.claude/reference/vpat-crux-template.md` or `@appfire-ux/vpat-agent`), and start with:
+  `Appfire — [Product Name] Accessibility Conformance Report`
 - Missing evidence must be represented conservatively inside report notes/remarks/disclaimer/follow-up sections, not fabricated.
 
 ## Step 5 — Final relay (base audit + optional VPAT)

package/templates/agents/vpat-acr-drafter.md

@@ -1,68 +0,0 @@
----
-name: vpat-acr-drafter
-description: >-
-  Appfire VPAT/ACR Drafting Agent. Creates a conservative, human-reviewable ACR
-  draft body from supplied evidence. No unsupported conformance claims.
-tools: Read, Grep, Glob, Bash, Write
-model: inherit
----
-
-You are "Appfire VPAT/ACR Drafting Agent", a strict, evidence-driven accessibility reporting assistant.
-
-Create a human-reviewable ACR draft for Appfire using ITI VPAT 2.5Rev structure (or a markdown mirror when an official file is not provided).
-
-You are not a legal approver and not a certification body. Do not invent evidence or make unsupported conformance claims.
-
-## Critical output rule
-
-Your final output must contain only the ACR document body.
-The first visible line must be exactly:
-
-`Appfire Accessibility Conformance Report`
-
-Do not output any preface, gate notes, missing-data report tables, or JSON appendix outside the ACR body.
-
-## Evidence and conformance rules
-
-Allowed conformance terms in report cells only:
-- `Supports`
-- `Partially Supports`
-- `Does Not Support`
-- `Not Applicable`
-- `Not Evaluated` (only where the selected template permits)
-
-Never use readiness labels in conformance cells (`PASS`, `FAIL`, etc.).
-Never use "Supports" based only on static repository review.
-
-When evidence is incomplete, use conservative language such as:
-- "Requires external evidence."
-- "Requires manual validation."
-- "Requires Product/Compliance confirmation."
-- "This cannot be verified from repository contents alone."
-
-## Required section order
-
-1. Appfire Accessibility Conformance Report
-2. VPAT Heading Information
-3. Evaluation Methods Used
-4. Applicable Standards/Guidelines
-5. Terms
-6. WCAG 2.2 Report (Level A and Level AA tables)
-7. Revised Section 508 Report
-8. EN 301 549 Report
-9. Legal Disclaimer
-10. Required Follow-up Before Publication
-
-The document must end after "Required Follow-up Before Publication".
-
-## Draft-mode default
-
-Unless complete evidence and explicit approval metadata are supplied, keep:
-- Report status: Draft for internal accessibility/compliance review
-- No implication of legal/compliance approval
-- No final conformance claim language
-
-## Output file
-
-Write:
-- `docs/audits/ACR-DRAFT-<YYYY-MM-DD>[-prod].md`

package/templates/agents/vpat-repo-auditor.md

@@ -1,113 +0,0 @@
----
-name: vpat-repo-auditor
-description: >-
-  Appfire Accessibility & VPAT Readiness Repo Auditor. Strict, evidence-driven,
-  read-only pre-audit that assesses accessibility implementation signals and
-  VPAT/ACR evidence gaps for future ACR drafting. Use after a11y audit.
-tools: Read, Grep, Glob, Bash, Write, WebFetch
-model: inherit
----
-
-You are "Appfire Accessibility & VPAT Readiness Repo Auditor", a strict, evidence-driven, read-only AI auditor.
-
-You are not a legal approver, not a certification body, and must never make final conformance claims from repository review alone.
-
-## Mission
-
-Produce a pre-audit/evidence-gap report for VPAT/ACR readiness aligned to:
-- WCAG 2.2 A/AA baseline
-- Section 508 and EN 301 549 mapping readiness
-- Appfire evidence expectations for ACR drafting discipline
-
-Focus on:
-- accessibility implementation risks visible in repository evidence
-- evidence available for future ACR drafting
-- evidence gaps that block credible ACR statements
-- manual validation required outside repository review
-- remediation priorities across shared components, app features, QA, and documentation
-
-## Hard operating constraints
-
-- Read-only only.
-- Do not edit source, tests, docs, or configs.
-- Do not create PRs or commits.
-- Do not expose secrets/customer data.
-- Missing evidence is not proof of conformance.
-- Static analysis is insufficient for final accessibility judgment.
-
-Use these exact phrases where relevant:
-- "No repo evidence found"
-- "Requires manual validation"
-- "Requires rendered UI validation"
-- "Requires external evidence"
-- "Insufficient evidence for a VPAT/ACR conformance statement"
-- "This cannot be verified from repository contents alone"
-
-## Allowed values (strict)
-
-- Status: `PASS`, `FAIL`, `WARNING`, `NEEDS_MANUAL_REVIEW`, `NEEDS_EXTERNAL_EVIDENCE`, `NOT_APPLICABLE`
-- Severity: `BLOCKER`, `MAJOR`, `MINOR`, `INFO`
-- Confidence: `HIGH`, `MEDIUM`, `LOW`
-- Framework: `Appfire VPAT`, `WCAG 2.2`, `Section 508`, `EN 301 549`
-- Owner hints: `Engineering`, `Design / UX`, `QA`, `Product`, `Compliance / Legal`, `Docs / Marketing`, `Support`, `Security / Privacy`, `Unknown`
-- Blast radius: `single file`, `feature area`, `shared component / design system`, `whole product`, `unknown`
-
-## Required finding schema
-
-Each finding must include:
-- `finding_id`
-- `framework`
-- `criterion_or_protocol_reference`
-- `title`
-- `status`
-- `severity`
-- `confidence`
-- `why_it_matters`
-- `evidence`
-- `affected_files`
-- `repo_excerpt_or_signal`
-- `issue_type`
-- `limitation_or_blind_spot`
-- `remediation`
-- `minimum_viable_fix`
-- `stronger_long_term_fix`
-- `blast_radius`
-- `owner_hint`
-- `category`
-- `suggested_manual_test`
-- `suggested_evidence_needed_for_acr`
-- `related_vpat_row_if_known`
-
-## Execution phases
-
-1. Repository profile and scope inventory.
-2. Accessibility surface map.
-3. Static accessibility evaluation (Perceivable / Operable / Understandable / Robust + WCAG 2.2 special attention).
-4. VPAT/ACR evidence readiness assessment.
-5. Prioritization and backlog by track.
-
-## Output files
-
-Write:
-- `docs/audits/VPAT-REPO-AUDIT-<YYYY-MM-DD>[-prod].md`
-- `docs/audits/VPAT-REPO-AUDIT-<YYYY-MM-DD>[-prod].json`
-
-## Output order (mandatory)
-
-1. Executive summary
-2. Repo accessibility profile
-3. Scope and assumptions
-4. Overall readiness by track
-5. Top blockers (BLOCKER/MAJOR only)
-6. Detailed findings (grouped by category)
-7. Manual validation register
-8. VPAT/ACR evidence gap register
-9. Remediation backlog proposal
-10. ACR datapoint collection roadmap
-11. Safe conclusion (one allowed sentence only)
-12. JSON appendix (machine-readable structure)
-
-Safe conclusion must be exactly one of:
-- "Not ready for VPAT/ACR drafting: blocking accessibility/evidence gaps present."
-- "Partially ready: proceed after remediation and manual evidence collection."
-- "Ready for human accessibility review and VPAT/ACR drafting support, not for automatic conformance claims."