neutral

Phase 22 — UI Remediation & Test Coverage

Brings the production React UI to full feature parity with the Figma reference prototype, fixes critical backend defects, connects 16 unused backend endpoints to new frontend pages, and expands test coverage to 80%+ across the UI codebase.

Status: Not Started Depends on: Phase 20 (React UI), Phase 14 (Production API) Migrations: None Branch: feature-react-ui

---

Why Now

With Phase 20 complete, Cruvero has a production React UI with 24 page components, 16 API clients, role-based access, and Playwright E2E coverage for 9 routes. However, a systematic comparison against the Figma reference prototype (prototypes/figma-reference-ui/) reveals significant gaps: 5 routes still render PlaceholderPage stubs, 15 reference page templates have no production counterpart, and 16 backend endpoints (audit, security, immune, events, quota, composites) have no frontend consumer.

Two critical backend defects also exist. First, runUISmokeServer is called at cmd/ui/main.go:74 but may be undefined depending on branch state — this must be verified and resolved. Second, the frontend's runs.ts:listPendingQuestions() calls GET /api/questions which is not registered as a backend route, causing the Questions page to fail silently when loading pending questions.

Beyond feature gaps, test coverage is minimal. The frontend has only 1 unit test file (security headers), 0 component tests, and no coverage reporting configured. The backend cmd/ui/ package has 4 test files covering only middleware — none of the 62 API handler functions are tested. SonarQube tracks Go coverage but is blind to JavaScript/TypeScript, and the 80% coverage threshold in coverage-thresholds.json is not enforced for frontend code.

Phase 22 closes all of these gaps through five sequential sub-phases: critical fixes, API-backed pages, new-backend pages, visual alignment, and comprehensive test coverage.

---

Architecture

Phase 22 follows a remediation architecture that maps reference prototype templates to production implementations:

1. Reference → Production Mapping: Each of the 33 reference pages is mapped to either an existing production page (18 matches), a PlaceholderPage replacement (5), or a new page (15). The mapping accounts for API shape differences between reference services and production endpoints.

2. Backend-First for New Pages: Pages in 22B use existing backend endpoints directly. Pages in 22C require new or extended backend endpoints before the frontend can be built.

3. Component Library Bridge: The reference uses shadcn/ui (Radix-based) + Tailwind v4 while production uses custom components + Tailwind v3. Phase 22D creates a mapping layer and adds missing shared components (badges, cards) without migrating to shadcn/ui.

4. Test-Last per Sub-Phase: Each sub-phase (22A-22D) delivers functional code. Phase 22E then sweeps across all pages to add comprehensive test coverage rather than testing incrementally per sub-phase.

---

Sub-Phases

Sub-Phase	Name	Prompts	Depends On
22A	Critical Fixes + PlaceholderPage Replacements	4	—
22B	API-Backed Feature Pages	5	22A
22C	New-Backend Feature Pages	5	22A
22D	Visual/Style Alignment	4	22B, 22C
22E	Test Coverage Expansion	5	22D

Total: 5 sub-phases, 23 prompts

Dependency Graph

22A (Critical Fixes) → 22B (API-Backed Pages) ──┐
                    └→ 22C (New-Backend Pages) ──┤→ 22D (Visual Alignment) → 22E (Test Coverage)

22B and 22C can run in parallel after 22A completes. 22D depends on both. 22E is last.

---

Sub-Phase Details

22A: Critical Fixes + PlaceholderPage Replacements

Resolves the two critical backend defects (runUISmokeServer, GET /api/questions) and replaces all 5 PlaceholderPage routes with real page implementations using existing backend endpoints. This unblocks all subsequent sub-phases.

22B: API-Backed Feature Pages

Builds 7 new pages that consume the 16 unused backend endpoints (audit, events, immune, quota, security, cost overview, operations). Each page gets a dedicated API client module. No backend changes needed — all endpoints already exist.

22C: New-Backend Feature Pages

Builds 8 pages that require new or extended backend endpoints: CostModels, MemoryPolicies, PII, PromptLibrary, ToolComposites, ToolsRegistry (enhanced), Speculation (full), and GraphViewer (full). Includes backend endpoint additions in cmd/ui/main.go.

22D: Visual/Style Alignment

Aligns all existing and new pages with the Figma reference design system. Maps shadcn/ui components to production equivalents, adds missing badge components, restructures sidebar navigation to include new pages, and verifies responsive layout and dark/light theme compliance.

22E: Test Coverage Expansion

Achieves 80%+ test coverage. Configures Vitest coverage reporting, adds component tests for all pages, expands E2E specs for new pages, adds backend handler tests for all cmd/ui/ API endpoints, and configures SonarQube for frontend coverage tracking.

---

Files Overview

New Files

File	Sub-Phase	Description
cmd/ui/ui_smoke.go	22A	Smoke server implementation (if missing)
cmd/ui/frontend/src/pages/ControlPage.tsx	22A	Control panel page
cmd/ui/frontend/src/pages/ToolRegistryPage.tsx	22A	Tool registry management page
cmd/ui/frontend/src/pages/GraphViewerPage.tsx	22A	Graph visualization page
cmd/ui/frontend/src/pages/SpeculationPage.tsx	22A	Speculation branch page
cmd/ui/frontend/src/pages/HealthPage.tsx	22A	System health dashboard
cmd/ui/frontend/src/pages/AuditPage.tsx	22B	Audit log viewer
cmd/ui/frontend/src/pages/EventsPage.tsx	22B	Event bus dashboard
cmd/ui/frontend/src/pages/ImmunePage.tsx	22B	Immune system viewer
cmd/ui/frontend/src/pages/QuotaPage.tsx	22B	Quota management
cmd/ui/frontend/src/pages/SecurityPage.tsx	22B	Security alerts
cmd/ui/frontend/src/pages/CostOverviewPage.tsx	22B	Aggregated cost overview
cmd/ui/frontend/src/pages/OperationsPage.tsx	22B	Operations dashboard
cmd/ui/frontend/src/api/audit.ts	22B	Audit API client
cmd/ui/frontend/src/api/events.ts	22B	Events API client
cmd/ui/frontend/src/api/immune.ts	22B	Immune API client
cmd/ui/frontend/src/api/quota.ts	22B	Quota API client
cmd/ui/frontend/src/api/security.ts	22B	Security API client
cmd/ui/frontend/src/pages/CostModelsPage.tsx	22C	Cost models page
cmd/ui/frontend/src/pages/MemoryPoliciesPage.tsx	22C	Memory policies page
cmd/ui/frontend/src/pages/PIIPage.tsx	22C	PII management page
cmd/ui/frontend/src/pages/PromptLibraryPage.tsx	22C	Prompt library page
cmd/ui/frontend/src/pages/ToolCompositesPage.tsx	22C	Tool composites page
cmd/ui/frontend/src/pages/EnhancedToolsRegistryPage.tsx	22C	Enhanced tool registry
cmd/ui/frontend/src/components/badges/*.tsx	22D	Badge components (Health, Quota, Risk, etc.)
cmd/ui/frontend/src/components/cards/*.tsx	22D	Shared card components
cmd/ui/frontend/src/__tests__/*.test.tsx	22E	Component tests for all pages
cmd/ui/*_test.go	22E	Backend handler tests

Modified Files

File	Sub-Phase	Change
cmd/ui/main.go	22A, 22C	Add /api/questions endpoint; add new backend endpoints for 22C pages
cmd/ui/frontend/src/App.tsx	22A, 22B, 22C	Replace PlaceholderPage routes; add new routes
cmd/ui/frontend/src/components/layout/Sidebar.tsx	22D	Add Governance/Security nav group, restructure items
cmd/ui/frontend/src/api/cost.ts	22B	Extend with aggregated cost functions
cmd/ui/frontend/vitest.config.ts	22E	Add coverage configuration
sonar-project.properties	22E	Add sonar.javascript.lcov.reportPaths

---

Success Metrics

Metric	Target
Feature parity with reference	100% of reference pages have production counterparts
PlaceholderPages remaining	0 (all 5 replaced)
Unused backend endpoints	0 (all 16 connected to frontend)
Frontend unit test coverage	>= 80% (measured by vitest --coverage)
Frontend component test files	>= 25 (one per page)
Backend cmd/ui/ test coverage	>= 80%
E2E spec files	>= 20 (cover all pages)
SonarQube frontend tracking	Configured and reporting
go build ./cmd/ui/	Passes without errors
Critical defects	0 (smoke server + questions endpoint fixed)

---

Code Quality Requirements

• ESLint: All new .tsx files pass existing ESLint config without warnings.
• TypeScript: Strict mode — no any types in new code, explicit return types on API functions.
• Vitest: All component tests pass; coverage reporter configured with v8 or istanbul provider.
• SonarQube: sonar.javascript.lcov.reportPaths set to frontend coverage output.
• Go: All new backend code passes go vet, staticcheck, and existing CI checks.
• Bundle size: No individual page chunk exceeds 50KB gzipped (per Phase 20F budget).

---

Risk Mitigation

Risk	Mitigation
Component library mismatch (shadcn/ui vs custom)	22D creates a mapping table and builds equivalent custom components; no shadcn/ui migration
API shape differences (reference services vs production endpoints)	Prompt files specify exact production endpoint paths with request/response types
runUISmokeServer may exist on another branch	22A-P1 checks git history; implements if missing
Large scope (23 prompts)	Sub-phases are independent after 22A; can ship 22A+22B as MVP
E2E test flakiness with new pages	22E-P4 uses Playwright's auto-waiting and test isolation patterns from Phase 20F
Backend endpoint additions (22C) may conflict with production API (Phase 14)	22C endpoints are registered in cmd/ui/main.go (UI server), not cmd/api/ (production API)

---

Relationship to Other Phases

Phase	Relationship
Phase 20 (React UI)	22 remediates gaps left by 20; builds on 20's routing, components, and API client patterns
Phase 14 (Production API)	22C backend endpoints in cmd/ui/ mirror patterns from Phase 14 route handlers
Phase 9B (Quotas)	22B QuotaPage consumes /api/quota endpoints from Phase 9B
Phase 9C (Audit)	22B AuditPage consumes /api/audit endpoints from Phase 9C
Phase 9D (Security)	22B SecurityPage/ImmunePage consume /api/security/alerts, /api/immune/* from Phase 9D
Phase 16 (Test Coverage)	22E extends Phase 16's coverage patterns to the UI codebase
Phase 12 (Events)	22B EventsPage consumes /api/events/* endpoints from Phase 12

---

Investigation Notes

• docs/notes/phase22-reference-audit.md — Full inventory of 34 reference pages and 9 service modules
• docs/notes/phase22-production-audit.md — Full inventory of 25 production pages, routes, API clients
• docs/notes/phase22-service-audit.md — All 62 backend endpoints mapped to frontend consumers
• docs/notes/phase22-test-baseline.md — Current test inventory and coverage configuration

---

Progress Notes

(none yet)