Quality Assurance

Proxima Console uses a phase-gated audit framework to ensure code quality, security, and UX standards are maintained across all development phases. No phase starts until the previous phase's audit is complete and all Critical and High findings are resolved.

Audit Framework

The full audit framework is defined in CODE_AUDIT.md in the repository root. It covers 13 audit dimensions:

#	Dimension	Description
1	Code Style & Consistency	Naming, formatting, linter compliance
2	Security	Auth, input validation, agent security, data protection
3	Architecture & Design Patterns	SOLID, DRY, KISS, separation of concerns
4	Error Handling & Resilience	Error types, retries, timeouts, graceful shutdown
5	Testing	Unit, integration, E2E, coverage targets
6	Performance	N+1 queries, pagination, caching, bundle size
7	Observability & Operations	Logging, metrics, tracing, health endpoints
8	Documentation & Developer Experience	README, API docs, inline comments
9	Type Safety & Data Contracts	TypeScript strict, API contracts, nullable handling
10	Accessibility	WCAG AA, keyboard navigation, ARIA, contrast
11	Internationalization	Extractable strings, locale formatting
12	License & Compliance	Dependency licenses, attribution
13	Frontend UX Audit	Comprehensive UX quality across 5 sub-dimensions

Not every phase requires all 13 dimensions. See the Summary Matrix in CODE_AUDIT.md for which dimensions apply to each phase.

Frontend UX Audit

The Frontend UX Audit (Dimension 13) is a mandatory audit before each phase starting from Phase 2. It was introduced after a comprehensive audit between Phase 2.5 and Phase 3 uncovered 85 findings that had accumulated silently across multiple phases.

Why it matters

UX debt compounds silently. Individual findings may seem minor, but collectively they degrade the user experience:

• 85 findings were discovered in one audit covering accessibility, responsive design, error handling, consistency, and performance
• Many findings existed since Phase 1 but were never caught
• Fixing them all at once required significant effort across three implementation passes
• Catching these issues at each phase boundary prevents accumulation

What to audit

The UX audit covers 5 sub-dimensions:

1. Accessibility (WCAG AA)

• aria-live regions for dynamic content
• Keyboard navigation for all interactive elements
• aria-label/aria-labelledby on icon-only buttons, selects, charts
• aria-pressed/aria-expanded on toggles and expandable rows
• Form validation with aria-invalid/aria-describedby
• Loading indicators with role="status" and sr-only text
• Skip-to-content link and <main> landmark
• Color contrast meeting WCAG AA 4.5:1 ratio
• Non-color indicators for status/severity

2. Responsive Design

• All tables wrapped in <ResponsiveTable>
• Toolbars/filters stack vertically on mobile
• Touch targets minimum 36px
• No horizontal overflow on 375px viewport
• Mobile alternatives for desktop-only features

3. Error Handling & Loading States

• Error states on all data-fetching components
• 404 handling for invalid entity IDs
• ErrorBoundary wrapping route outlets
• Skeleton loading states for initial loads
• Empty states with icon + descriptive text

4. Consistency & Patterns

• Shared PageTitle component on all pages
• DeleteConfirmDialog on all delete operations
• DialogDescription + Cancel button on form dialogs
• Entity names in toast messages
• Filter state in URL via useSearchParams
• Standardized empty state styling

5. Performance UX

• refetchIntervalInBackground: false on polling
• Heavy components lazy-loaded via React.lazy()
• Derived state wrapped in useMemo
• Filter inputs debounced
• No N+1 API patterns
• Lists paginated or virtualized

How to run

I need you to audit the following code using the Proxima Console audit framework.

Phase just completed: [phase number]
Component: frontend

Audit Dimension 13 (Frontend UX Audit) — all 5 sub-dimensions:
- Accessibility (WCAG AA)
- Responsive Design
- Error Handling & Loading States
- Consistency & Patterns
- Performance UX

Audit all files in frontend/src/

Gate criteria

• All Critical and High findings must be resolved before starting the next phase
• Medium findings should be tracked and resolved within 2 phases
• Store results in docs/audits/PHASE-X-UX-AUDIT.md

Phase-Gated Schedule

Each phase has specific audit dimensions. The general flow:

Complete Phase X work
        |
        v
Run audit (applicable dimensions from Summary Matrix)
        |
        v
Fix all Critical + High findings
        |
        v
Commit report to docs/audits/PHASE-X-AUDIT.md
        |
        v
Gate Decision = APPROVED
        |
        v
Begin Phase X+1

Finding Severity Levels

Severity	Definition	Action
Critical	Security vulnerability, data loss risk, or production crash	Must fix before next phase. Blocks release.
High	Significant bug, major pattern violation, or missing critical test	Must fix before next phase.
Medium	Code smell, minor pattern violation, missing edge case test	Fix within 2 phases.
Low	Style inconsistency, minor improvement	Fix opportunistically.
Info	Observation or positive note	No action required.

Audit Reports

Completed audit reports are stored in docs/audits/. The directory now holds 20+ reports — one per phase plus targeted reviews of cross-cutting areas. The full set is the source of truth; representative reports include:

Report	Scope
PHASE-2-AUDIT.md … PHASE-5-RELEASE-AUDIT.md	Per-phase gate audits (Phase 2 through Phase 5)
PHASE-3-UX-AUDIT.md, PHASE-4-UX-AUDIT.md, FRONTEND-UX-AUDIT.md	Frontend UX audits
AUTH-AUDIT-2026-06-02.md, RBAC-AUDIT-2026-06-01.md	Authentication and RBAC reviews
CLI-V1-AUDIT.md, TERMINAL-ACCESS-STANDARDS-AUDIT.md	pc CLI and terminal-access reviews
CMDB-PHASE-1-2-AUDIT.md, SERVICE-DESK-AUDIT.md, mcp-gap-audit.md	Feature-area audits (CMDB, service desk, MCP)

See docs/audits/ for the complete, current list.

Running Automated Checks

Before any manual audit, run automated tooling first:

# Go
golangci-lint run ./...
govulncheck ./...

# Frontend
npm run lint
npm audit
npx tsc --noEmit

# Full test suite
make test && make lint && make test-race

Then proceed with manual review for architecture, patterns, UX, and logic issues that automated tools cannot catch.