@appfire-ux/audit-agent 0.20260708.0 → 0.20260708.1

package/package.json

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

@@ -61,6 +61,9 @@ 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
 ├── prod-assets/              # only when orchestrator shares PNG captures across agents
 ├── ux-audit/
 │   ├── UX-AUDIT-<date>[-prod].md
@@ -78,6 +81,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 |
@@ -159,13 +240,32 @@ 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`.
+
+## 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.
 
 ## 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
+
+Remind the user the a11y `.json` feeds "AI Agent: VPAT Document" (Confluence, CRUX) for the ACR draft.