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:

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:

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

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

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:

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

.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:

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

Fallback if Sail is unavailable:

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:

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:

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

Optional/documented:

Browser audit only. No runtime code changed.

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

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.