@appfire-ux/audit-agent 0.20260708.2 → 0.20260708.4

package/README.md

@@ -54,7 +54,9 @@ npx @appfire-ux/guidelines
 | `.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/commands/full-audit.md` | `/full-audit [--agents ux,ui,a11y]` — parallel run of selected agents, combined summary MD+HTML |
+| `.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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260708.2",
+  "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.",
   "license": "MIT",
   "publishConfig": {

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

@@ -0,0 +1,68 @@
+---
+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

@@ -0,0 +1,113 @@
+---
+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."

package/templates/commands/full-audit.md

@@ -12,7 +12,7 @@ Arguments passed by the user: `$ARGUMENTS`
 - **Scope path** — optional directory (default: whole repo).
 - `--agents ux,ui,a11y` — subset of agents to run (default: all three).
 - `--critique hard|balanced` — critique intensity for UX/UI (default: `hard`).
-- `--with-vpat` — after full audit completes, run two VPAT agents in sequence: repository readiness auditor, then ACR drafting agent.
+- `--with-vpat` — run two VPAT agents in sequence after the base audit: repository readiness auditor, then ACR drafting agent. **Default: enabled**.
 - `--static-only` — skip runtime/screenshots/scans for all agents; warn the user that the UI audit will be much weaker and most a11y criteria become NEEDS_MANUAL_REVIEW.
 - `--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`).
@@ -65,9 +65,9 @@ Hard fail gate:
 ├── RECOMMENDATIONS-TABLE-<date>[-prod].md
 ├── RECOMMENDATIONS-TABLE-<date>[-prod].html
 ├── RECOMMENDATIONS-TABLE-<date>[-prod].json
-├── VPAT-REPO-AUDIT-<date>[-prod].md              # only when --with-vpat
-├── VPAT-REPO-AUDIT-<date>[-prod].json            # only when --with-vpat
-├── ACR-DRAFT-<date>[-prod].md                    # only when --with-vpat
+├── VPAT-REPO-AUDIT-<date>[-prod].md              # when VPAT sequence enabled (default)
+├── VPAT-REPO-AUDIT-<date>[-prod].json            # when VPAT sequence enabled (default)
+├── ACR-DRAFT-<date>[-prod].md                    # when VPAT sequence enabled (default)
 ├── prod-assets/              # only when orchestrator shares PNG captures across agents
 ├── ux-audit/
 │   ├── UX-AUDIT-<date>[-prod].md
@@ -258,9 +258,9 @@ Before writing AUDIT-SUMMARY:
    (or repo-local `docs/audits/build-html-reports.mjs` if present)
 5. Optionally serve preview: `npx --yes serve <out-dir> -p 4173` and give user links to `*.html`.
 
-## Step 4 — Optional VPAT post-sequence (`--with-vpat`)
+## Step 4 — VPAT post-sequence (enabled by default)
 
-Run this only when `--with-vpat` is set. This is strictly sequential:
+Run this by default. Skip only if user explicitly disables VPAT sequence for this run. This is strictly sequential:
 1. `vpat-repo-auditor` runs first, consuming:
    - `a11y-audit/A11Y-AUDIT-<date>[-prod].md`
    - `a11y-audit/A11Y-AUDIT-<date>[-prod].json`