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

Feature Specification: Tenantial Enterprise UI Audit Foundation

Feature Branch: 323-tenantial-enterprise-ui-audit-foundation Created: 2026-05-17 Status: Draft Input: User supplied full Spec 323 draft, plus the follow-up requirement that Spec 323 becomes the ongoing Design Coverage Gate baseline for future UI features. Type: Docs-first / browser-audit / productization inventory / UI Design Registry baseline Runtime Posture: Read-only audit first. No runtime UI redesign, feature implementation, route behavior change, authorization change, schema change, or business-logic change.

Dependencies

• Spec 318: Admin Surface Scope and Shell Context Audit
• Spec 319: Environment-Owned Surface Routing and Shell Context Contract
• Spec 320: Workspace-Owned Analysis Surface Registration and Shell Cutover
• Spec 321: Alerts / Audit Log Environment Filter Contract Decision
• Spec 322: Browser No-Drift Regression Guard
• Current platform-dev repo truth after Spec 322 validation

Candidate Source And Guardrail Result

Candidate source: Direct user-provided manual promotion for Spec 323. The active auto-prep queue in docs/product/spec-candidates.md is intentionally empty, so this package proceeds only because the user supplied a complete explicit candidate.

Completed-spec guardrail: No existing specs/323-* package or 323-* branch was present before generation. Specs 318 through 322 were inspected as dependency and historical context only; their completed task markers, close-out notes, validation results, screenshots, and review evidence remain untouched.

Close alternatives deferred:

• 324-tenantial-strategic-surface-target-mockups: deep target mockups for P0/P1 strategic pages after the inventory exists.
• 325-tenantial-design-system-and-state-patterns: shared component/state cleanup rules after current UI debt is classified.
• 326-tenantial-domain-pattern-coverage-pass: grouped domain pattern coverage after route/page archetypes are known.
• 327-tenantial-enterprise-ui-implementation-wave-1: runtime UI implementation after design decisions and mockups/patterns exist.

Spec Candidate Check

• Problem: Tenantial has many reachable product, admin, workspace, environment, customer, monitoring, review, provider, support, and settings surfaces, but there is no complete design-coverage registry proving every route has a product role and target-state decision.
• Today's failure: Later design work can improve only obvious pages while leaving hidden or direct-route surfaces raw, technical, misclassified, customer-unsafe, or unassigned to any target mockup/pattern/design-system cleanup path.
• User-visible improvement: Operators, customer reviewers, auditors, and product reviewers get a route/page inventory that says what exists, what each page is for, how product-ready it is, and what design treatment it needs next.
• Smallest enterprise-capable version: Create a docs-only audit structure; discover routes and page classes; capture feasible desktop screenshots for strategic/domain surfaces; classify every discovered page into archetype, design depth, repo truth, and coverage decision; record unresolved pages; and establish the ongoing Design Coverage Gate.
• Explicit non-goals: No runtime redesign, no Blade/Filament/Livewire edits, no route rewrites, no permissions changes, no migrations, no feature creation, no high-fidelity mockups for every page, no per-page follow-up spec explosion, no product claims not backed by repo truth.
• Permanent complexity imported: A maintained documentation registry, page archetype labels, design-depth labels, repo-truth labels, page report templates, screenshot artifacts, coverage-matrix updates, and an ongoing feature DoD for UI coverage. No runtime enum, database, service, or UI framework is introduced.
• Why now: Specs 318 through 322 stabilized route/shell/context correctness. The next bottleneck is productization coverage: every reachable page needs a design decision before strategic mockups or implementation waves start.
• Why not local: A local audit of one page or domain would miss hidden/direct routes and would not create the durable gate that prevents future UI debt.
• Approval class: Core Enterprise
• Red flags triggered: Foundation terminology and classification system. Defense: the classification is docs-only audit metadata with no runtime semantic layer, and it directly prevents customer-facing and operator-facing trust gaps.
• Score: Nutzen 2 | Dringlichkeit 2 | Scope 2 | Komplexitaet 1 | Produktnaehe 2 | Wiederverwendung 2 | Gesamt: 11/12
• Decision: approve

Summary

Establish the first Tenantial Enterprise UI/UX Audit foundation.

This spec discovers the reachable product UI surface, captures screenshots where feasible, classifies every page into a product/page archetype, evaluates each page against Tenantial enterprise-product expectations, and creates a design-coverage inventory that drives later mockup, pattern, and implementation specs.

This is not a redesign implementation spec.

The goal is to answer, repo-based:

• Which pages/routes currently exist?
• Which pages are reachable in normal workspace, environment, customer, and operator flows?
• Which pages are strategic product surfaces?
• Which pages are utility/admin/supporting surfaces?
• Which pages feel too technical, admin-like, or implementation-driven?
• Which pages need individual target mockups later?
• Which pages can be covered by shared page patterns later?
• Which pages are deprecated, hidden, internal-only, or require manual review?

Spec 323 also establishes the ongoing UI Design Registry rule: future UI-relevant specs must not create reachable unclassified page debt.

Product Context

Tenantial/TenantPilot is moving from a technically strong governance/admin product toward a sellable Enterprise SaaS platform experience.

The repo already contains strong foundations around:

• OperationRun truth
• Evidence
• Reviews
• Review Packs
• Drift findings
• Restore safety
• Provider health
• Workspace entitlements
• Capability-first RBAC
• Audit foundations
• Supportability
• Customer health
• Operational controls

The current bottleneck is not only backend capability. The larger productization gap is whether users can understand, trust, consume, and act on those capabilities through calm, decision-first, customer-safe surfaces.

Problem Statement

The product has accumulated many pages, panels, routes, resources, dashboards, detail pages, settings surfaces, and operational views. Some likely already feel product-shaped. Others may still feel like raw Filament/admin resources, technical diagnostics, implementation artifacts, or internal tooling exposed as product UI.

Without a full route/page inventory, later design work risks:

• improving only the obvious pages
• missing hidden but reachable pages
• over-designing small utility pages
• creating too many isolated mockups
• creating inconsistent follow-up specs
• redesigning pages without knowing their user, purpose, or product role
• implementing brand styling without fixing information architecture

Objective

Create a complete Tenantial Enterprise UI Audit Foundation that:

1. Discovers all relevant UI pages/routes.
2. Captures current-state screenshots where feasible.
3. Classifies every page into a page archetype.
4. Assigns every page a design depth.
5. Evaluates every page using a common enterprise readiness rubric.
6. Identifies strategic surfaces requiring individual target mockups.
7. Identifies domain pages that should use shared patterns.
8. Identifies small utility/admin pages that should use design-system cleanup rules.
9. Produces a master design-coverage inventory.
10. Creates a backlog of later specs without implementing UI changes.
11. Establishes an ongoing Design Coverage Gate for future UI-relevant specs.

Non-Goals

This spec must not:

• redesign runtime pages
• change Blade views
• change Filament resources
• change Livewire components
• change navigation behavior
• change route behavior
• change authorization behavior
• change business logic
• change database schema
• introduce new product capabilities
• create high-fidelity SVG mockups for every page
• create individual follow-up specs for every small page
• rename product concepts in runtime
• remove pages
• modify tenant/workspace/environment context behavior
• run broad refactors
• run destructive commands

Mockups, design-system work, and implementation changes belong to later specs.

Core Principle

The full product environment is considered designed only when every discovered route is either:

1. covered by an individual target experience mockup,
2. mapped to an approved domain-level page pattern,
3. mapped to a reusable design-system/component pattern,
4. or explicitly marked as deprecated, hidden, internal-only, out of scope, or requiring manual review.

No reachable page may remain unclassified, undesigned, or without a recommended target state.

Spec 323 creates the first inventory and classification layer for this rule.

Ongoing Feature Design Coverage Gate

After Spec 323, every new feature that introduces or changes a reachable UI surface must update the UI/UX audit coverage artifacts.

A feature is not UI-complete if it adds a reachable page, action, modal, drawer, form, table, state, or customer-facing surface without a design coverage decision.

Required for every new UI surface:

• Add or update entry in docs/ui-ux-enterprise-audit/route-inventory.md
• Assign primary page archetype
• Assign design depth
• Assign repo-truth level
• Link to existing domain pattern or component pattern
• Add screenshot if the surface is strategic or materially different
• Add page report if the surface introduces a new product decision, workflow, dangerous action, or customer-facing experience
• Add to docs/ui-ux-enterprise-audit/unresolved-pages.md if the surface cannot be reviewed yet
• Update docs/ui-ux-enterprise-audit/design-coverage-matrix.md

New features must not create unclassified UI debt.

UI/UX Coverage Requirements For Later Specs

Every future UI-relevant spec should carry this standard DoD:

• Route/page is added to the UI audit inventory.
• Page archetype is assigned.
• Design depth is assigned.
• Existing pattern is reused or a new pattern need is documented.
• Strategic surfaces have screenshot or target mockup follow-up.
• Dangerous actions have impact/confirmation/evidence review.
• Customer-facing surfaces are checked for customer-safe language and data exposure.
• No new page remains unclassified.

Not every new feature needs a new mockup:

• New strategic page -> individual target image/mockup/follow-up UI spec.
• New normal domain page -> existing domain pattern.
• New small admin/utility page -> design-system cleanup rules.
• New modal/drawer/action -> component/state pattern review.
• Experimental or internal feature -> internal/manual-review marker.

Future Feature Coverage Guardrail

Spec 323 establishes the UI/Productization Coverage baseline.

After this spec, every future feature spec that adds, removes, renames, or materially changes a reachable UI surface must update or explicitly acknowledge the UI coverage artifacts.

A UI surface includes:

• page
• route
• navigation item
• table
• form
• modal
• drawer
• wizard step
• action
• dangerous action confirmation
• empty/loading/error state
• customer-facing view
• operator workflow surface

Required decision for every affected surface:

• page archetype
• design depth
• repo-truth level
• target pattern or mockup need
• customer-safe review need
• dangerous-action review need

A feature must not be considered complete if it creates unclassified UI debt.

Ongoing DoD Addition for Future Specs

If a spec changes reachable UI:

• UI Surface Impact section completed.
• Route/page inventory updated or no-impact rationale documented.
• Design coverage matrix updated where needed.
• Existing pattern reused or missing pattern documented.
• Dangerous actions reviewed where applicable.
• Customer-facing surfaces reviewed where applicable.
• No new reachable UI surface remains unclassified.

Tenantial Brand / UX Direction

Use the Tenantial brand and UX context as the product lens.

Tenantial should feel:

• calm
• precise
• premium
• operator-first
• evidence-first
• enterprise-grade
• workspace-aware
• trustworthy
• controlled

Tenantial must not feel like:

• generic blue SaaS
• playful startup UI
• raw admin console
• debug dashboard
• helpdesk clone
• Microsoft admin center mirror
• noisy cybersecurity dashboard
• overconfident compliance marketing

For every page, answer:

Can a non-technical decision-maker, customer stakeholder, auditor, or operator understand within five seconds what this page is about, why it matters, and what should happen next?

Product UX Rules

Every audited page must be evaluated against these principles:

• decision-first
• evidence-first
• source-of-truth first
• workspace-first
• capability-aware
• RBAC-aware
• progressive disclosure
• no misleading status
• clear next action
• customer-safe where applicable
• diagnostics second
• evidence third
• technical depth available but not dominant

Required Truth-Layer Distinctions

The audit must distinguish between these truth layers:

Truth Layer	Question	Examples
Execution Truth	What actually ran?	OperationRun state, timestamps, actor, failure reason, run result
Artifact Truth	What object/configuration/report exists?	baseline profile, backup snapshot, stored report, evidence artifact
Backup Truth	What was backed up, when, and from which source?	restore point, backup version, object coverage, scope
Recovery Evidence	What was restored, from what source, by whom, and with what result?	restore run, restore proof, safety gate result, recovery evidence snapshot
Operator Next Action	What should the user do next?	review finding, accept risk, assign owner, export evidence, inspect failed run, reconnect provider, verify permissions

Pages that mix these layers without hierarchy must be flagged.

Page Archetypes

Every page must be classified into one primary archetype and optionally one secondary archetype.

Allowed archetypes:

1. Overview / Dashboard
2. Findings / Inbox
3. Evidence / Audit
4. Backup / Restore
5. Drift / Diff
6. Inventory
7. Reviews
8. Exceptions / Accepted Risk
9. Operations / Monitoring
10. Provider / Integration
11. Workspace / Tenant Context
12. Settings / Admin
13. Support / Diagnostics
14. Commercial / Entitlements
15. Customer Workspace
16. Auth / Access
17. Utility / Internal
18. Deprecated / Legacy
19. Manual Review Required

If a page cannot be confidently classified, mark it as Manual Review Required and explain why.

Design Depth Classification

Every page must receive one design-depth classification.

Design Depth	Use For	Later Output
Strategic Surface	Pages central to demo, sellability, customer experience, operator workflow, product positioning, or dangerous/high-impact actions	Individual target experience, individual Dark/Light SVG or mockup, individual follow-up spec
Domain Pattern Surface	Important but repeatable domain pages	Shared domain pattern, grouped follow-up spec, optional pattern mockup
Design-System Cleanup Surface	Smaller utility/admin pages	Shared table/form/state/action patterns; no individual mockup unless unusually important
Internal / Deprecated / Hidden	Pages not treated as product surfaces	Reason and decision to hide, retire, protect, or leave internal
Manual Review Required	Route/page cannot be safely evaluated	Human inspection before design claims

Repo-Truth Classification

Every page and recommendation must mark product truth level.

Allowed values:

• repo-verified
• plausible-existing
• foundation-only
• spec-only
• conceptual-future-state
• unknown

Hard rule:

Do not present conceptual or spec-only UI as implemented product truth.

Scope

In Scope

• Laravel/Filament admin pages
• workspace-level pages
• environment/tenant-scoped pages
• monitoring pages
• operations pages
• governance pages
• review pages
• customer-facing review surfaces if present
• provider/integration pages
• settings/admin pages
• support/diagnostic pages
• auth/access/no-access pages where reachable
• navigation and shell structure
• page screenshots
• current copy/labels
• page purpose
• primary actions
• dangerous actions
• empty/loading/error states where visible
• responsive notes where feasible
• design coverage matrix
• recommended follow-up spec grouping
• ongoing Design Coverage Gate for future UI specs
• Constitution principle for UI/Productization Coverage
• Spec template UI Surface Impact and UI/Productization Coverage blocks
• Agent implementation prompt guardrail
• CI/review script guard for UI surface changes

Out of Scope

• Runtime UI changes
• component implementation
• CSS/theme implementation
• route rewrites
• localization implementation
• database changes
• auth/RBAC changes
• feature creation
• code cleanup unrelated to audit docs
• runtime deployment behavior changes
• full suite stabilization
• high-fidelity SVG target mockups for all pages

Required Output Structure

Implementation of this spec must create:

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

If docs/brand/tenantial-brand-context.md does not exist, implementation must create a minimal placeholder reference file or document that it is required before later mockup specs.

Do not invent final brand assets if official assets are missing.

Spec 323 must also update the process guardrail surfaces that make the registry durable:

.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

User Scenarios & Testing

User Story 1 - Discover the reachable UI surface (Priority: P1)

As a product reviewer, I need a repo-based inventory of reachable UI pages/routes so later design work covers the actual application rather than only obvious navigation entries.

Independent Test: A reviewer can open docs/ui-ux-enterprise-audit/route-inventory.md and see every discovered UI route/page assigned an audit ID, source, reachability, scope, archetype, design depth, repo truth, and target coverage decision or unresolved marker.

Acceptance Scenarios:

1. Given the repo has Filament resources, pages, routes, and navigation definitions, when the audit runs discovery, then each discovered UI surface appears in route-inventory.md or unresolved-pages.md.
2. Given a page is hidden, guarded, redirect-only, or browser-blocked, when it cannot be fully inspected, then it is still inventoried with a reason and no unsupported design claim.

User Story 2 - Classify pages into product/design coverage decisions (Priority: P1)

As a product/design lead, I need each page classified by archetype, design depth, and repo truth so strategic mockups and pattern specs can be scoped without over-designing utility pages.

Independent Test: A reviewer can filter the inventory and coverage matrix to identify strategic, domain-pattern, cleanup, internal/deprecated, and manual-review pages.

Acceptance Scenarios:

1. Given a page is central to sellability or a core workflow, when it is reviewed, then it is marked as Strategic Surface and appears in strategic-surfaces.md.
2. Given a page is a repeatable list/detail/admin surface, when it is reviewed, then it is assigned to a domain pattern or design-system cleanup path rather than receiving an unnecessary individual mockup requirement.

User Story 3 - Capture current state and page-level findings (Priority: P1)

As a future implementation agent, I need current screenshots and concise page reports so follow-up specs can see current-state problems without rediscovering every surface.

Independent Test: Every reviewed page has a page report under docs/ui-ux-enterprise-audit/page-reports/, and every reachable strategic page has a desktop screenshot or a documented reason why no screenshot exists.

Acceptance Scenarios:

1. Given a strategic page is reachable in the browser, when the audit reviews it, then a desktop screenshot is saved under screenshots/desktop/ and linked from inventory/report files.
2. Given a page exposes dangerous actions, customer-facing language, misleading status, or workspace/environment ambiguity, when it is reviewed, then the page report flags the issue and recommends target handling.

User Story 4 - Establish future Design Coverage Gate (Priority: P2)

As an engineering reviewer, I need a lightweight ongoing gate so future features do not add reachable UI surfaces without design classification.

Independent Test: README.md, route-inventory.md, templates, the coverage matrix, Spec Kit templates, agent implement prompts, PR template, and CI guard document/enforce how future specs update the registry when adding or changing reachable pages, modals, drawers, tables, forms, actions, or customer-facing states.

Acceptance Scenarios:

1. Given a future feature adds a new reachable page, when its spec closes, then it has updated inventory, archetype, design depth, repo truth, pattern/mockup decision, and matrix counts.
2. Given a future feature adds a modal/drawer/action rather than a page, when it is UI-relevant, then it is mapped to a component/state pattern or documented as manual review/internal if not reviewable yet.
3. Given a future PR changes guarded UI surface files without updating coverage artifacts, when the PR fast-feedback guard runs, then it fails unless the active spec contains a checked No UI surface impact decision.

Edge Cases

• Route exists in route:list but redirects before rendering.
• Route is guarded by auth, workspace membership, capability, or platform-plane access.
• Page requires seeded data, provider connection, review pack, operation run, or customer-facing context to render meaningfully.
• Page throws a runtime error during browser audit.
• Page is reachable only through direct URL, global search, row action, modal, nested resource, or cluster navigation.
• Route exists for legacy/deprecated behavior but should not be treated as product UI.
• Page exposes old tenant terminology where workspace/environment language should be checked.
• Screenshot capture is blocked by local browser instability, missing app server, auth fixture, or required provider state.
• A future feature changes only a modal/drawer/action/state; it must still receive a design coverage decision even if no new route exists.

Requirements

Functional Requirements

• FR-323-001: The audit must create the required docs/ui-ux-enterprise-audit/ structure and template files.
• FR-323-002: The audit must discover UI surfaces using multiple methods: route discovery, file-based Filament/Livewire/view discovery, navigation/provider inspection, and browser navigation where feasible.
• FR-323-003: The route inventory must include the required columns: ID, Route / URL, Source, Page Name, Area, Scope, Reachability, Auth/RBAC Notes, Primary Archetype, Secondary Archetype, Design Depth, Repo Truth, Screenshot, Page Report, and Notes.
• FR-323-004: Every discovered page/route must receive a primary archetype or be listed in unresolved pages with a reason.
• FR-323-005: Every discovered page/route must receive a design-depth classification or be listed in unresolved pages with a reason.
• FR-323-006: Every discovered page/route must receive a repo-truth classification or be listed in unresolved pages with a reason.
• FR-323-007: Every reachable strategic page must have a desktop screenshot or a documented blocker in unresolved-pages.md.
• FR-323-008: Every reviewed page must have a page report using the page audit template.
• FR-323-009: The design coverage matrix must summarize totals, coverage by area, coverage by archetype, missing/unclear coverage, and recommended next specs.
• FR-323-010: Strategic surfaces must be listed with P0/P1/P2 priority, route, reason, current risk, and recommended target artifact.
• FR-323-011: Grouped follow-up candidates must avoid one spec per page and must group later work by domain, shared problem, spec type, mockup need, pattern sufficiency, and priority.
• FR-323-012: Unresolved pages must record the reason using one of the required reason categories: route not reachable, auth blocked, requires seeded data, requires provider connection, throws runtime error, redirect loop, unclear ownership, legacy/deprecated ambiguity, or manual browser inspection required.
• FR-323-013: Page reports must review the first-five-seconds test, productization issues, information inventory, status/trust signals, dangerous actions, enterprise readiness scores, top issues, target direction, and later spec recommendation.
• FR-323-014: Dangerous-action pages must be flagged for restore, delete, approve exception, accept risk, close finding, rerun backup, export evidence, change RBAC, disconnect integration, change entitlement, suspend workspace, invite user, or remove user actions.
• FR-323-015: Customer-facing or auditor-facing pages must be flagged for customer-safe language and data exposure risks.
• FR-323-016: Workspace/environment context ambiguity must be flagged where route, shell, breadcrumbs, filter chips, or terminology conflict.
• FR-323-017: Misleading status or false-success states must be flagged; unknown, stale, pending, unconfirmed, not scanned, not reviewed, not connected, or not evaluated must not be treated as verified success.
• FR-323-018: The README must explain purpose, what was done, what was not done, how to read the inventory/reports, classification models, and recommended next specs.
• FR-323-019: The audit must establish the ongoing Feature Design Coverage Gate in README/template guidance so future UI features update the registry.
• FR-323-020: If docs/brand/tenantial-brand-context.md is missing, the implementation must create a minimal placeholder reference or document the missing brand context as a blocker for later mockup specs.
• FR-323-021: No runtime UI, route, auth, database, or business-logic files may be changed by this spec.
• FR-323-022: The Constitution must include UI/Productization Coverage as a durable product principle requiring explicit coverage decisions for reachable UI surfaces.
• FR-323-023: The Spec Kit templates and implementation prompts must require a UI Surface Impact decision and UI/Productization Coverage details for future UI-relevant specs.
• FR-323-024: PR fast-feedback must include a mechanical guard that fails when guarded UI surface files change without either coverage artifact updates or a checked No UI surface impact decision in a changed spec.

Non-Functional Requirements

• NFR-323-001: The audit must be repo-based and must not present conceptual/spec-only UI as implemented product truth.
• NFR-323-002: Markdown artifacts must be reviewable, stable, and useful for follow-up implementation agents without requiring the full browser session to be replayed.
• NFR-323-003: Screenshot naming must use stable audit IDs and slugs.
• NFR-323-004: The audit must keep browser work bounded and document missing tablet/mobile coverage rather than blocking the spec on exhaustive responsive review.
• NFR-323-005: The audit must avoid creating new runtime taxonomy, enum, database, UI framework, or code layer.
• NFR-323-006: Validation must include git diff --check and the UI/Productization Coverage guard script.
• NFR-323-007: Full runtime suite must not be run unless future implementation discovers runtime changes, which are out of scope for this spec.

Data / Truth-Source Requirements

• Runtime truth: apps/platform routes, Filament resources/pages/clusters/providers, Livewire components, Blade views, and reachable browser pages.
• Documentation truth: Specs 318 through 322, product roadmap/spec-candidates, current UI standards, and the generated audit artifacts.
• Screenshot truth: Browser-captured current-state PNGs under the audit screenshots directory.
• No new persisted product truth: No migrations, tables, models, enums, or runtime registries.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Current-state audit of existing pages	no runtime change	Existing Filament/native/custom surfaces are only observed	navigation, shell, tables, forms, modals, page state	route, query, shell, page, screenshot artifacts	no	Documentation-only audit
UI Design Registry baseline	no runtime change	N/A	future spec DoD and review workflow	documentation artifacts	no	Future UI specs update registry

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes, documentation and audit governance only
• Interaction classes observed: navigation, status messaging, action hierarchy, dangerous actions, table/form states, empty states, evidence/report viewers, provider/onboarding surfaces, customer review surfaces
• Existing standards reused: docs/ui/tenantpilot-enterprise-ui-standards.md, docs/ui/operator-ux-surface-standards.md, docs/product/standards/filament-native-enterprise-ui.md, Filament v5 blueprint rules, Specs 318 through 322 context/shell coverage
• New runtime abstraction introduced?: no
• Bounded deviation / spread control: The audit may introduce docs-only classification metadata. It must not become runtime code or a mandatory UI presenter/registry.

OperationRun UX Impact

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

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: observation only
• Provider-owned seams: Provider/Graph/Microsoft/Entra Tenant terminology where it is genuinely external-provider identity.
• Platform-core seams: Workspace, Managed Environment, Environment route/shell/filter behavior, customer review workspace, provider connection product surfaces.
• Neutral terms preserved: Workspace, Environment, Managed Environment, Provider Connection, Operation, Evidence, Review.
• Retained provider-specific semantics and why: The audit must not relabel runtime copy, but it must flag where provider or legacy tenant wording leaks into customer/operator product language.
• Follow-up path: Product language findings go into grouped follow-up candidates or manual-review notes, not runtime changes in this spec.

Proportionality Review

• New source of truth?: no runtime source of truth; yes, docs-only audit registry truth for design coverage.
• New persisted entity/table/artifact?: no persisted runtime entity/table; yes Markdown docs and screenshot artifacts.
• New abstraction?: no runtime abstraction.
• New enum/state/reason family?: no runtime enum/state; docs-only page archetype, design-depth, and repo-truth labels.
• New cross-domain UI framework/taxonomy?: no runtime framework; docs-only coverage taxonomy.
• Current operator problem: Pages can remain reachable without product role, decision hierarchy, customer-safe review, or target-state decision.
• Existing structure is insufficient because: Existing specs and standards define principles and route/shell contracts, but no artifact inventories every route/page and assigns design coverage.
• Narrowest correct implementation: Markdown registry plus screenshots/page reports; no runtime registry, no component library, no redesign.
• Ownership cost: Future UI specs must update the registry.
• Alternative intentionally rejected: Building all target mockups or implementation changes in this spec.
• Current-release truth: Productization audit over existing repo/runtime surfaces.

Testing / Lane / Runtime Impact

• Runtime impact: none expected.
• Test purpose / classification: Documentation/process guardrail validation plus optional Browser audit session; no Pest runtime tests required because app runtime behavior is unchanged.
• Affected validation lanes: docs/prep validation plus PR guard script; browser session if app is opened for screenshots.
• Narrowest proving commands: git diff --check and bash scripts/check-ui-productization-coverage HEAD.
• Fixture/helper/factory/seed/context cost risks: none; browser screenshots should use existing local app state and document blockers instead of adding seeders.
• Heavy-family additions: none.
• Browser coverage: Manual/browser audit screenshots only, not automated browser tests.
• Full suite: Not run for Markdown-only implementation.

Discovery Requirements

Implementation must use multiple discovery methods:

• cd apps/platform && ./vendor/bin/sail artisan route:list
• Fallback if Sail is unavailable: cd apps/platform && php artisan route:list
• File-based discovery in:
  • 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
• Navigation discovery through current navigation definitions, clusters, resource registration, page registration, and panel providers.
• Browser discovery where feasible for reachable pages.

Screenshot Requirements

• Every reachable strategic page requires a desktop screenshot.
• Every reachable domain pattern page should have a desktop screenshot when feasible.
• Utility/admin screenshots are optional if the page is simple and covered by inventory/page report.
• Tablet/mobile screenshots are optional and should be captured for app shell, dashboard/overview, customer review workspace, governance inbox, operations, evidence overview, and critical forms when feasible.

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

Enterprise Readiness Rubric

Each reviewed page receives scores from 0 to 5 for:

• Information Architecture
• Information Density
• Target User Clarity
• Sellability / Platform Feel
• Progressive Disclosure
• Layout & Hierarchy
• Design-System Fit
• Accessibility
• Responsive UX
• Component Quality
• UX Writing
• Performance Perception

Success Criteria

• SC-323-001: docs/ui-ux-enterprise-audit/README.md exists and documents audit purpose, scope, classifications, and next specs.
• SC-323-002: route-inventory.md exists and all discovered UI routes/pages are classified or listed in unresolved-pages.md.
• SC-323-003: Every discovered page has a primary archetype, design-depth classification, and repo-truth classification unless unresolved with reason.
• SC-323-004: Every reachable strategic page has a desktop screenshot or documented screenshot blocker.
• SC-323-005: Every reviewed page has a page report.
• SC-323-006: design-coverage-matrix.md summarizes total coverage.
• SC-323-007: strategic-surfaces.md identifies P0/P1/P2 strategic surfaces.
• SC-323-008: grouped-follow-up-candidates.md groups later specs instead of creating one spec per page.
• SC-323-009: Dangerous-action pages, customer-facing pages, workspace/environment ambiguity, and misleading status risks are flagged.
• SC-323-010: Ongoing Feature Design Coverage Gate is documented in the audit README/templates.
• SC-323-011: No runtime UI, route, auth, DB, or business-logic changes are made.
• SC-323-012: Constitution, Spec Kit templates, implementation prompts, PR template, and PR fast-feedback guard make the future UI Surface Impact decision explicit.
• SC-323-013: git diff --check passes.
• SC-323-014: bash scripts/check-ui-productization-coverage HEAD passes for the current non-runtime guardrail change.
• SC-323-015: Final implementation report explicitly states full suite was not run.

Assumptions

• The app can be opened locally through Sail or an existing local dev server for at least some screenshots.
• Some pages require auth, seeded data, provider connection, operation/review/evidence fixtures, or platform-plane access and may be unresolved.
• Desktop screenshots are the minimum useful baseline for strategic surfaces; tablet/mobile coverage can be deferred when costly.
• The audit may use Tenantial naming as the product lens while preserving TenantPilot/TenantAtlas repo terminology where runtime truth still uses it.
• Future specs can update the audit registry without making Spec 323 a runtime dependency.

Open Questions

No open question blocks preparation. Implementation should document any route/page that cannot be safely classified as Manual Review Required.

Recommended Next Specs

1. 324-tenantial-strategic-surface-target-mockups
2. 325-tenantial-design-system-and-state-patterns
3. 326-tenantial-domain-pattern-coverage-pass
4. 327-tenantial-enterprise-ui-implementation-wave-1

Spec 323 must not implement those specs.

Required Final Report Shape

The implementation final response for Spec 323 must include:

• changed/created files
• route/page count
• screenshot count
• strategic surface count
• unresolved page count
• validation commands run
• explicit note that no runtime code was changed
• explicit note that full suite was not run