@appfire-ux/audit-agent 0.20260708.0 → 0.20260708.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appfire-ux/audit-agent",
-  "version": "0.20260708.0",
+  "version": "0.20260708.2",
   "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/commands/full-audit.md

@@ -1,6 +1,6 @@
 ---
-description: Run ux-auditor, ui-auditor and a11y-auditor in parallel — guideline compliance + UI/usability + accessibility/VPAT audit
-argument-hint: [scope-path] [--agents ux,ui,a11y] [--critique hard|balanced] [--static-only] [--lang pl|en] [--out-dir <path>] [--prod]
+description: Run ux-auditor, ui-auditor and a11y-auditor in parallel — optional VPAT post-sequence with repo-audit + ACR draft
+argument-hint: [scope-path] [--agents ux,ui,a11y] [--critique hard|balanced] [--with-vpat] [--static-only] [--lang pl|en] [--out-dir <path>] [--prod]
 ---
 
 Run **all three** audit agents on this repository **in parallel**: **ux-auditor** (guideline compliance), **ui-auditor** (UI & usability) and **a11y-auditor** (accessibility / VPAT readiness).
@@ -12,6 +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.
 - `--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`).
@@ -61,6 +62,12 @@ Hard fail gate:
 <out-dir>/
 ├── AUDIT-SUMMARY-<date>[-prod].md
 ├── AUDIT-SUMMARY-<date>[-prod].html
+├── 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
 ├── prod-assets/              # only when orchestrator shares PNG captures across agents
 ├── ux-audit/
 │   ├── UX-AUDIT-<date>[-prod].md
@@ -78,6 +85,84 @@ Hard fail gate:
 
 Relative image paths in MD/HTML: `assets/<file>.png` — never base64, never `../prod-assets/`.
 
+## New required artifact — UX Recommendations Table
+
+In addition to existing reports, `/full-audit` MUST generate a consolidated recommendations table artifact in **English**.
+
+Output files (required) under `<out-dir>/`:
+- `RECOMMENDATIONS-TABLE-<date>[-prod].md`
+- `RECOMMENDATIONS-TABLE-<date>[-prod].html`
+- `RECOMMENDATIONS-TABLE-<date>[-prod].json` (machine-readable for npm/automation)
+
+Purpose:
+- planning-ready recommendations across UX/UI/A11Y with clear priority, implementation intent, justification, and expected user value.
+
+Canonical table schema (required columns, exact order):
+1. `Area`
+2. `Priority` (P0/P1/P2)
+3. `Recommended UX Work`
+4. `Justification`
+5. `Expected Value (User Perspective)`
+
+Row requirements:
+- Minimum: 6 rows
+- Must include at least:
+  - Empty/first-run states
+  - Navigation IA/wayfinding
+  - Feedback/confidence loops
+  - Destructive action safety
+  - Accessibility semantics/manual validation
+  - Responsive usability
+- Every row must be actionable (not only diagnostic).
+- Language: English only.
+- Keep recommendations deduplicated and normalized across UX/UI/A11Y reports.
+
+Priority mapping rules:
+- `P0` = major user risk, activation blocker, or high operational risk
+- `P1` = significant productivity/confidence/accessibility gain
+- `P2` = meaningful optimization, lower urgency
+
+Data source rules:
+- Build from:
+  - `ux-audit/UX-AUDIT-<date>[-prod].md`
+  - `ui-audit/UI-AUDIT-<date>[-prod].md`
+  - `a11y-audit/A11Y-AUDIT-<date>[-prod].md`
+  - `AUDIT-SUMMARY-<date>[-prod].md`
+- Do not invent runtime evidence.
+- If static-only mode is used, include a note that confidence is lower.
+
+Required JSON format:
+```json
+{
+  "meta": {
+    "date": "YYYY-MM-DD[-prod]",
+    "language": "en",
+    "sourceReports": [
+      "ux-audit/UX-AUDIT-...",
+      "ui-audit/UI-AUDIT-...",
+      "a11y-audit/A11Y-AUDIT-...",
+      "AUDIT-SUMMARY-..."
+    ]
+  },
+  "columns": [
+    "Area",
+    "Priority",
+    "Recommended UX Work",
+    "Justification",
+    "Expected Value (User Perspective)"
+  ],
+  "rows": [
+    {
+      "Area": "...",
+      "Priority": "P0|P1|P2",
+      "Recommended UX Work": "...",
+      "Justification": "...",
+      "Expected Value (User Perspective)": "..."
+    }
+  ]
+}
+```
+
 ## Role division (/full-audit)
 
 | Agent | Owns | Same protocol |
@@ -85,6 +170,8 @@ Relative image paths in MD/HTML: `assets/<file>.png` — never base64, never `..
 | **ux-auditor** | Guideline compliance: tokens, a11y, copy, messaging, personas | STOP & ASK, MD+HTML+PNG, Definition of done |
 | **ui-auditor** | IA, consistency, layout, interaction, responsiveness | STOP & ASK, MD+HTML+PNG, Definition of done |
 | **a11y-auditor** | Deep accessibility: WCAG 2.2 A/AA, axe-core scan, VPAT/ACR datapoints | STOP & ASK, MD+HTML+PNG+JSON, no over-claiming |
+| **vpat-repo-auditor** (optional) | Evidence-gap pre-audit for VPAT/ACR readiness | read-only, strict non-overclaiming, MD+JSON |
+| **vpat-acr-drafter** (optional) | Human-reviewable ACR draft body from evidence package | output only ACR body, conservative conformance language |
 
 - Each agent writes to its own `ux-audit/`, `ui-audit/` or `a11y-audit/` subfolder with its own `assets/`.
 - Use `prod-assets/` **only** when orchestrator captures once and agents reuse identical PNGs — each agent copies into local `assets/` for Confluence-relative paths.
@@ -135,7 +222,7 @@ Follow Shared deliverables: MD+HTML+PNG, Definition of done.
 If STOP & ASK triggers mid-run, pause and ask user — do not fake verified-runtime.
 ```
 
-## Step 3 — Combined summary + HTML (after all agents finish)
+## Step 3 — Combined summary + HTML (after UX/UI/A11Y finish)
 
 Before writing AUDIT-SUMMARY:
 - validate coverage matrix
@@ -159,13 +246,61 @@ Before writing AUDIT-SUMMARY:
    - Do not finalize `/full-audit` if UX+UI combined produce fewer than 6 MAJOR findings,
      unless runtime coverage is explicitly blocked and documented.
    - If `coverage_percent < 100`, mark the run `INCOMPLETE AUDIT` and do not present as finished.
-3. Generate HTML for **all** reports:
+3. Build `RECOMMENDATIONS-TABLE-<date>[-prod].md|.json` from UX/UI/A11Y/SUMMARY reports:
+   - Use required columns in exact order.
+   - Ensure at least 6 actionable, deduplicated rows with required topic coverage.
+   - Force language to English.
+   - Include confidence-lower note if static-only mode was used.
+4. Generate HTML for **all** reports (including `RECOMMENDATIONS-TABLE-*.html`):
    ```bash
    node node_modules/@appfire-ux/audit-agent/scripts/build-html-reports.mjs --dir <out-dir>
    ```
    (or repo-local `docs/audits/build-html-reports.mjs` if present)
-4. Optionally serve preview: `npx --yes serve <out-dir> -p 4173` and give user links to `*.html`.
+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`)
+
+Run this only when `--with-vpat` is set. 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`
+   - `AUDIT-SUMMARY-<date>[-prod].md`
+   - coverage + recommendations artifacts
+   Output:
+   - `<out-dir>/VPAT-REPO-AUDIT-<date>[-prod].md`
+   - `<out-dir>/VPAT-REPO-AUDIT-<date>[-prod].json`
+2. `vpat-acr-drafter` runs second, consuming the full evidence package including `VPAT-REPO-AUDIT`.
+   Output:
+   - `<out-dir>/ACR-DRAFT-<date>[-prod].md`
+
+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`
+- Missing evidence must be represented conservatively inside report notes/remarks/disclaimer/follow-up sections, not fabricated.
+
+## Step 5 — Final relay (base audit + optional VPAT)
+
+When `--with-vpat` is enabled, include VPAT artifact paths and:
+- one-line VPAT readiness status
+- one-line ACR draft status (draft for human review, not final conformance claim)
+
+## Definition of done extension
+
+`/full-audit` is complete only if all are true:
+1. Existing UX/UI/A11Y/SUMMARY artifacts exist (MD + HTML + A11Y JSON).
+2. Recommendations table artifacts exist (MD + HTML + JSON).
+3. Table has required columns and minimum row coverage.
+4. Priorities are assigned and justified from audit evidence.
+5. If `--with-vpat`: VPAT repo-audit MD+JSON and ACR draft MD exist.
 
 ## Relay to the user
 
-MD + HTML paths (all reports), combined severity counts, Baseline Accessibility Score + safe conclusion (a11y), top 3 issues, capture coverage, Limitations, local preview URLs, whether parallel run and STOP & ASK occurred. Remind the user the a11y `.json` feeds "AI Agent: VPAT Document" (Confluence, CRUX) for the ACR draft.
+MD + HTML paths (all reports), combined severity counts, Baseline Accessibility Score + safe conclusion (a11y), top 3 issues, capture coverage, Limitations, local preview URLs, whether parallel run and STOP & ASK occurred.
+
+Always include:
+- paths to recommendations table `.md`, `.html`, `.json`
+- one-line summary of highest-priority (`P0`) recommendation themes
+
+If `--with-vpat`, also return VPAT artifact paths and confirm the ACR draft is conservative and requires human compliance/legal review before publication.