TenantAtlas/specs/323-tenantial-enterprise-ui-audit-foundation/plan.md

# Implementation Plan: Tenantial Enterprise UI Audit Foundation

**Branch**: `323-tenantial-enterprise-ui-audit-foundation`
**Date**: 2026-05-17
**Spec**: `specs/323-tenantial-enterprise-ui-audit-foundation/spec.md`
**Status**: Draft
**Runtime posture**: Documentation/browser-audit only. No runtime UI, route, auth, DB, or business-logic changes.

## Summary

Create a durable UI/UX audit foundation for Tenantial/TenantPilot by discovering reachable product UI surfaces, capturing feasible screenshots, classifying every discovered page, producing a design coverage matrix, and establishing a living UI Design Registry gate for future UI-relevant specs.

The implementation output lives under `docs/ui-ux-enterprise-audit/` plus a minimal brand context placeholder only if `docs/brand/tenantial-brand-context.md` is missing. The follow-up governance output updates the Constitution, Spec Kit templates, implementation prompts, PR template, and PR fast-feedback guard. It must not modify app runtime files.

## Technical Context

**Language / Version**: PHP 8.4.15 runtime, but this spec is Markdown/browser-audit work.
**Primary Framework**: Laravel 12.52.0.
**Admin UI**: Filament 5.2.1.
**Reactive Layer**: Livewire 4.1.4.
**Database**: PostgreSQL via Sail, not modified.
**Testing**: No Pest runtime tests required for Markdown-only output.
**Validation Lanes**: Docs/process validation through `git diff --check`; UI/Productization Coverage guard script; browser audit session if screenshots are captured.
**Target Platform**: Laravel monolith in `apps/platform`.
**Project Type**: Web application.
**Performance Goals**: Keep browser audit bounded; document blockers instead of forcing all routes through screenshots.
**Constraints**: No application implementation, no migrations, no packages, no env var changes, no queue/scheduler/storage changes, no route/auth changes, no broad full-suite runs.
**Scale / Scope**: All relevant reachable UI routes/pages discovered from Laravel route list, Filament pages/resources/clusters/providers, Livewire/views/routes, navigation definitions, and browser pass where feasible.

Package posture:

- Filament v5 requires Livewire v4.0+; this repo uses Livewire 4.1.4.
- Laravel 12 panel providers are registered in `apps/platform/bootstrap/providers.php`; this spec does not add or modify panel providers.
- No Filament assets are added. No `filament:assets` deployment change is expected.

## Current Repo Truth

Spec 323 builds on the route/shell/context work from Specs 318 through 322. The adjacent repo truth includes:

```text
specs/318-admin-surface-scope-shell-context-audit/
specs/319-environment-owned-surface-routing-shell-context-contract/
specs/320-workspace-owned-analysis-surface-registration-shell-cutover/
specs/321-alerts-audit-log-environment-filter-contract-decision/
specs/322-browser-no-drift-regression-guard/
docs/ui/tenantpilot-enterprise-ui-standards.md
docs/ui/operator-ux-surface-standards.md
docs/product/standards/filament-native-enterprise-ui.md
docs/product/spec-candidates.md
docs/product/roadmap.md
```

Relevant runtime discovery surfaces for audit only:

```text
apps/platform/app/Filament/Pages/
apps/platform/app/Filament/Resources/
apps/platform/app/Filament/Clusters/
apps/platform/app/Livewire/
apps/platform/resources/views/
apps/platform/routes/
apps/platform/app/Providers/Filament/
apps/platform/bootstrap/providers.php
```

Implementation may read these files and run read-only route/browser commands. It must not edit app runtime files.

## Project Structure

### Spec Artifacts

```text
specs/323-tenantial-enterprise-ui-audit-foundation/spec.md
specs/323-tenantial-enterprise-ui-audit-foundation/plan.md
specs/323-tenantial-enterprise-ui-audit-foundation/tasks.md
specs/323-tenantial-enterprise-ui-audit-foundation/checklists/requirements.md
```

### Audit Artifacts To Create During Implementation

```text
docs/ui-ux-enterprise-audit/
├── README.md
├── route-inventory.md
├── design-coverage-matrix.md
├── strategic-surfaces.md
├── grouped-follow-up-candidates.md
├── unresolved-pages.md
├── screenshots/
│   ├── desktop/
│   ├── tablet/
│   └── mobile/
├── page-reports/
└── templates/
    ├── page-audit-template.md
    ├── route-inventory-template.md
    └── design-coverage-template.md
```

Conditional artifact:

```text
docs/brand/tenantial-brand-context.md
```

Create the conditional artifact only if no brand context exists, and keep it as a minimal placeholder/reference blocker for later mockup specs.

### Process Guardrail Artifacts To Update

```text
.specify/memory/constitution.md
.specify/templates/spec-template.md
.specify/templates/plan-template.md
.specify/templates/tasks-template.md
.specify/templates/checklist-template.md
.codex/prompts/speckit.implement.md
.github/agents/speckit.implement.agent.md
.gitea/pull_request_template.md
.gitea/workflows/test-pr-fast-feedback.yml
scripts/check-ui-productization-coverage
```

## UI / Surface Guardrail Plan

- **Guardrail scope**: Documentation-only audit of existing surfaces plus future UI Design Coverage Gate baseline.
- **Native vs custom classification summary**: Existing surfaces may be native Filament, custom Blade/Livewire, or mixed; Spec 323 observes and classifies but does not change them.
- **Shared-family relevance**: Navigation, shell, page reports, tables, forms, modals, drawers, actions, status states, dangerous actions, evidence/report viewers, customer review surfaces.
- **State layers in scope**: route path, query string, shell, page state, modal/drawer/action state when visible, screenshot artifact, inventory classification.
- **Audience modes in scope**: operator, customer reviewer, auditor, platform/support user where reachable.
- **Decision/diagnostic/raw hierarchy plan**: Page reports must classify default-visible decision content, diagnostic content, and raw/support evidence.
- **Raw/support gating plan**: Flag raw IDs, JSON, provider/internal fields, logs, or unsupported compliance claims when default-visible on customer/operator surfaces.
- **One-primary-action / duplicate-truth control**: Page reports must flag pages where primary next action is unclear or equal-weight technical/debug actions compete with user workflow.
- **Handling modes by drift class or surface**: `individual target mockup required`, `domain-level pattern sufficient`, `design-system cleanup sufficient`, `internal/deprecated`, or `manual review required`.
- **Repository-signal treatment**: Any discovered route without classification is a blocker for Spec 323 completion.
- **Special surface test profiles**: N/A for runtime tests; browser audit evidence is manual/artifact-based.
- **Required tests or manual smoke**: Browser audit/screenshot pass where feasible; `git diff --check`; UI/Productization Coverage guard script.
- **Exception path and spread control**: If a page cannot be reached or evaluated, record it in `unresolved-pages.md` with reason.
- **Active feature PR close-out entry**: Guardrail / Design Coverage Registry Baseline.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes, documentation governance only.
- **Systems touched**: Audit docs, screenshots, templates, route inventory, coverage matrix, future feature DoD.
- **Shared abstractions reused**: Existing UI standards, Filament v5 rules, Specs 318-322 route/shell context language.
- **New abstraction introduced? why?**: No runtime abstraction. The docs-only UI Design Registry is introduced to prevent future unclassified reachable UI debt.
- **Why existing structure was insufficient**: Existing standards say how good surfaces should behave, but no master route/page inventory assigns every route a design decision.
- **Bounded deviation / spread control**: The registry is maintained as Markdown artifacts and does not become a runtime registry, enum, presenter, or UI framework.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no.
- **Central contract reused**: N/A.
- **Delegated UX behaviors**: N/A.
- **Surface-owned behavior kept local**: Existing OperationRun pages may be audited as current-state UI.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: Observation only.
- **Provider-owned seams**: Microsoft/Entra/Graph tenant identity and provider connection semantics where already present.
- **Platform-core seams**: Workspace, Environment, Managed Environment, route/shell context, product page role.
- **Neutral platform terms / contracts preserved**: Workspace, Environment, Managed Environment, Provider Connection, Operation, Evidence, Review.
- **Retained provider-specific semantics and why**: Runtime copy is not changed in this spec. Audit reports flag provider-specific terms when they leak into platform-core or customer/operator copy.
- **Bounded extraction or follow-up path**: Product language and IA findings are routed to follow-up specs, not fixed here.

## Constitution Check

### Pre-Implementation

- **Inventory-first / snapshots-second**: Pass. The spec inventories UI routes/pages only and does not alter inventory/snapshot domain truth.
- **Read/write separation**: Pass. The spec is read-only; no product write actions are introduced.
- **Graph contract path**: Pass. No Graph calls are introduced. Browser audit must not trigger Graph writes.
- **Deterministic capabilities**: Pass. Capability derivation is not changed.
- **Workspace/tenant isolation**: Pass. The audit records scope and RBAC notes but does not change authorization.
- **RBAC-UX**: Pass. Dangerous actions and customer-facing exposure are audited only.
- **OperationRun UX**: N/A.
- **Test governance**: Pass with docs-only lane. Browser audit is manual screenshot evidence, not new test family.
- **Proportionality**: Pass. Docs-only registry avoids runtime taxonomy/frameworking.
- **Shared Pattern First**: Pass. Future pages map to individual mockup, domain pattern, design-system pattern, internal/deprecated, or manual review.
- **Filament-native UI**: Pass. Existing Filament surfaces are observed; no custom UI is introduced.
- **Spec Candidate Gate**: Pass. Direct manual promotion with 11/12 score and bounded docs-only scope.

### Post-Design

No constitutional violation is expected.

Implementation must stop and update `spec.md` and `plan.md` before making any runtime UI, route, auth, database, test-suite, or business-logic changes.

## Filament v5 Output Contract

- **Livewire v4.0+ compliance**: This repo uses Livewire 4.1.4; Spec 323 changes no Livewire code.
- **Provider registration location**: Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`; no provider changes.
- **Globally searchable resources**: No Resource code changes. The audit may record global-search reachability only; it must not enable or disable global search.
- **Destructive/high-impact actions**: No action behavior changes. The audit must flag pages exposing dangerous actions and record whether visible confirmation/authorization/evidence posture appears adequate.
- **Asset strategy**: No assets added; no new `filament:assets` deployment step.
- **Testing plan**: Markdown/process validation via `git diff --check` and `bash scripts/check-ui-productization-coverage HEAD`; browser audit and screenshots where feasible; no full suite because app runtime behavior is unchanged.

## Test Governance Check

- **Test purpose / classification by changed surface**: N/A for runtime; docs/process validation plus manual browser audit.
- **Affected validation lanes**: docs validation plus UI/Productization Coverage guard script; optional browser session for screenshots.
- **Why this lane mix is the narrowest sufficient proof**: The deliverable is Markdown/screenshot/process guardrail artifacts, not app runtime behavior.
- **Narrowest proving command(s)**: `git diff --check`; `bash scripts/check-ui-productization-coverage HEAD`.
- **Fixture / helper / factory / seed / context cost risks**: none. Do not add seeders or fixtures for screenshots.
- **Expensive defaults or shared helper growth introduced?**: no.
- **Heavy-family additions, promotions, or visibility changes**: none.
- **Surface-class relief / special coverage rule**: Documentation-only audit; future UI specs use the ongoing coverage gate.
- **Closing validation and reviewer handoff**: Reviewer checks route/page counts, screenshot counts, unresolved counts, strategic surfaces, and no runtime file changes.
- **Budget / baseline / trend follow-up**: none.
- **Review-stop questions**: Any unclassified discovered route, unsupported product truth claim, missing strategic screenshot reason, or runtime file change blocks completion.
- **Escalation path**: document-in-feature for unresolved pages; follow-up-spec for strategic mockups/pattern specs.
- **Active feature PR close-out entry**: Guardrail / Design Coverage Registry Baseline.
- **Why no dedicated follow-up spec is needed for the gate itself**: Spec 323 establishes the baseline; Specs 324-327 are already reserved for mockups, patterns, domain coverage, and implementation.

## Technical Approach

### Phase 1 - Create Audit Structure

Create the audit directory tree and required Markdown templates. Add a README that defines audit purpose, non-goals, classification models, how to read reports, the ongoing Design Coverage Gate, and next specs.

### Phase 2 - Discover Routes And Pages

Use safe read-only discovery:

```bash
cd apps/platform && ./vendor/bin/sail artisan route:list
```

Fallback if Sail is unavailable:

```bash
cd apps/platform && php artisan route:list
```

Then inspect Filament pages/resources/clusters/providers, Livewire components, views, routes, and navigation definitions. Build `route-inventory.md` with stable audit IDs (`UI-001`, `UI-002`, ...).

### Phase 3 - Browser Pass And Screenshots

Open reachable pages where feasible. Prioritize:

1. strategic likely pages
2. domain hub/list pages
3. customer-facing pages
4. dangerous-action pages
5. onboarding/provider pages
6. dashboard/shell pages

Capture desktop screenshots for reachable strategic pages. Capture domain screenshots where practical. Record blockers in `unresolved-pages.md`.

### Phase 4 - Page Reports

Create `page-reports/<audit-id>-<page-slug>.md` for every reviewed page using the page audit template. Keep reports concise and consistent rather than over-polished.

### Phase 5 - Coverage Matrix And Strategic Surfaces

Summarize totals and coverage by area/archetype/design depth. Populate strategic surfaces with P0/P1/P2 priority and recommended target artifact.

### Phase 6 - Grouped Follow-Up Candidates

Create grouped follow-up candidates by domain:

- Customer Review Workspace
- Decision / Governance Inbox
- Operations / Monitoring
- Evidence / Audit
- Reviews / Review Packs
- Drift / Findings
- Backup / Restore
- Provider / Onboarding
- Inventory
- Settings / Admin
- Support / Diagnostics
- Commercial / Entitlements
- Auth / Access
- Global App Shell / Navigation
- Global Tables / Forms / States

### Phase 7 - Ongoing Design Coverage Gate

Document how future UI-relevant specs update the registry. Include the standard UI/UX Coverage Requirements checklist and decision model for strategic pages, domain pages, utility pages, modals/drawers/actions, and internal/manual-review surfaces.

Also codify the gate outside the audit docs:

- add UI/Productization Coverage to the Constitution
- add UI Surface Impact and UI/Productization Coverage blocks to the Spec Kit spec template
- carry the planning/task/checklist guardrails into the plan, tasks, and checklist templates
- add the pre-implementation guardrail to the Codex and GitHub Spec Kit implement prompts
- add a PR-template checkbox
- add a diff-based PR fast-feedback guard that requires coverage artifacts or a checked `No UI surface impact` decision when guarded UI paths change

### Phase 8 - Validation And Close-Out

Run `git diff --check` and `bash scripts/check-ui-productization-coverage HEAD`. Do not run the full suite because app runtime behavior is unchanged. Final report includes created/changed files, route/page count, screenshot count, strategic surface count, unresolved page count, validation commands, no-runtime-code-change note, and full-suite-not-run note.

## Data / Migration / Deployment Impact

- **Migrations**: none.
- **Models / DB**: none.
- **Env vars**: none.
- **Queues / scheduler**: none.
- **Storage / volumes**: screenshot artifacts are committed Markdown-adjacent files under `docs/`; no runtime storage changes.
- **Deployment**: no runtime deployment impact. PR fast-feedback gains a lightweight guard step before the Sail/PHP test lane.
- **Filament assets**: no asset registration; no new `filament:assets` requirement.

## Browser Audit Plan

Use the in-app browser or a local browser session when feasible. Prefer the Browser plugin for local targets if a dev server URL is known. Use Laravel Boost `get_absolute_url` when sharing a project URL, but final output need not share a runtime URL unless a dev server is started.

Screenshots must use stable paths:

```text
docs/ui-ux-enterprise-audit/screenshots/desktop/<audit-id>-<page-slug>.png
docs/ui-ux-enterprise-audit/screenshots/tablet/<audit-id>-<page-slug>.png
docs/ui-ux-enterprise-audit/screenshots/mobile/<audit-id>-<page-slug>.png
```

Do not add seeders or runtime fixtures to make screenshots pretty. If a page needs data/provider/auth state that is unavailable, document the blocker.

## Risks And Controls

| Risk | Control |
| --- | --- |
| Route inventory misses hidden/direct pages | Use route list, file-based discovery, navigation inspection, and browser pass. |
| Audit invents future-state product truth | Require repo-truth classification and prohibit conceptual/spec-only claims as implemented. |
| Too many pages become individual mockup specs | Use design-depth model; group domain and cleanup pages. |
| Screenshot pass becomes too expensive | Require desktop screenshots only for reachable strategic pages; document blockers. |
| Future features ignore the registry | Add ongoing Design Coverage Gate and UI/UX Coverage Requirements to README/templates, Spec Kit templates, implement prompts, PR template, and PR fast-feedback guard. |
| Runtime changes slip into docs-first work | Final diff review must show only docs/screenshot/spec artifacts; stop on app code changes. |
| Brand assets are missing | Create only minimal placeholder/reference blocker; do not invent final assets. |

## Validation Plan

Required:

```bash
git diff --check
bash scripts/check-ui-productization-coverage HEAD
```

Optional/documented:

```text
Browser audit only. No runtime code changed.
```

Do not run unless runtime changes are made, which is out of scope:

```text
Full suite
Broad unrelated test lanes
Test expectation updates
```

## Readiness Gate

Spec 323 is ready for implementation when:

- `spec.md`, `plan.md`, and `tasks.md` exist.
- The scope is docs/browser-audit only.
- Required output structure and classification models are explicit.
- The ongoing Design Coverage Gate is included.
- Validation is bounded to Markdown/screenshot/process guardrail work.
- No unresolved preparation issue requires application implementation.