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

Tasks: Tenantial Enterprise UI Audit Foundation

Input: Spec artifacts from specs/323-tenantial-enterprise-ui-audit-foundation/ Prerequisites: spec.md, plan.md Runtime posture: Documentation/browser-audit only. No runtime UI, route, auth, DB, or business-logic changes.

Phase 1: Guardrails And Repo Context

• T001 Re-read specs/323-tenantial-enterprise-ui-audit-foundation/spec.md, plan.md, and tasks.md before implementation starts.
• T002 Re-read AGENTS.md, .specify/memory/constitution.md, docs/ai-coding-rules.md, and relevant docs/*-guidelines.md files before making audit artifacts.
• T003 Re-read docs/ui/tenantpilot-enterprise-ui-standards.md, docs/ui/operator-ux-surface-standards.md, and docs/product/standards/filament-native-enterprise-ui.md for the audit lens.
• T004 Re-read Specs 318 through 322 as historical/context dependencies without editing their completed artifacts.
• T005 Verify the implementation starts from branch 323-tenantial-enterprise-ui-audit-foundation and the working tree has no unrelated user changes.
• T006 Confirm the implementation diff remains limited to audit docs, Spec 323 artifacts, Spec Kit process templates/prompts, PR template/workflow guardrails, and scripts/check-ui-productization-coverage; no app runtime files are changed.

Phase 2: Audit Structure And Templates

• T007 Create docs/ui-ux-enterprise-audit/ and subdirectories screenshots/desktop/, screenshots/tablet/, screenshots/mobile/, page-reports/, and templates/.
• T008 Create docs/ui-ux-enterprise-audit/templates/page-audit-template.md with the full page audit structure from specs/323-tenantial-enterprise-ui-audit-foundation/spec.md.
• T009 Create docs/ui-ux-enterprise-audit/templates/route-inventory-template.md with required inventory columns and classification options.
• T010 Create docs/ui-ux-enterprise-audit/templates/design-coverage-template.md with summary, coverage by area, coverage by archetype, missing coverage, and next spec sections.
• T011 Create docs/ui-ux-enterprise-audit/README.md explaining audit purpose, what Spec 323 did, what it did not do, how to read inventory/reports, classification models, the ongoing Design Coverage Gate, and recommended next specs.
• T012 If docs/brand/tenantial-brand-context.md is missing, create a minimal placeholder reference explaining that official Tenantial brand assets/context are required before later mockup specs.

Phase 3: Route And File-Based Discovery

• T013 Run cd apps/platform && ./vendor/bin/sail artisan route:list and use cd apps/platform && php artisan route:list only if Sail is unavailable.
• T014 Inspect apps/platform/app/Filament/Pages/ and record discovered pages in docs/ui-ux-enterprise-audit/route-inventory.md.
• T015 Inspect apps/platform/app/Filament/Resources/ and record list/create/edit/view/custom pages in docs/ui-ux-enterprise-audit/route-inventory.md.
• T016 Inspect apps/platform/app/Filament/Clusters/ and record cluster navigation/page implications in docs/ui-ux-enterprise-audit/route-inventory.md.
• T017 Inspect apps/platform/app/Livewire/, apps/platform/resources/views/, and apps/platform/routes/ for reachable UI surfaces not obvious from Filament resources.
• T018 Inspect apps/platform/app/Providers/Filament/ and apps/platform/bootstrap/providers.php to identify panel paths, registered discovery locations, and admin/system plane boundaries.
• T019 Inspect current navigation and shell support files related to workspace hubs, environment-owned surfaces, alerts/audit, provider connections, operations, reviews, evidence, settings, and support.
• T020 Assign stable sequential audit IDs (UI-001, UI-002, ...) for every discovered UI route/page in docs/ui-ux-enterprise-audit/route-inventory.md.
• T021 For every discovered row in docs/ui-ux-enterprise-audit/route-inventory.md, fill source, page name, area, scope, reachability, auth/RBAC notes, primary archetype, design depth, repo truth, screenshot link if available, page report link, and notes.
• T022 Add any route/page that cannot be safely evaluated to docs/ui-ux-enterprise-audit/unresolved-pages.md with one required blocker reason.

Phase 4: Browser Pass And Screenshots

• T023 Determine the local app URL and auth/browser feasibility without changing runtime configuration.
• T024 Open reachable strategic candidate pages in the browser and capture required desktop screenshots under docs/ui-ux-enterprise-audit/screenshots/desktop/.
• T025 Capture preferred desktop screenshots for reachable domain pattern pages under docs/ui-ux-enterprise-audit/screenshots/desktop/ when feasible.
• T026 Capture optional tablet screenshots under docs/ui-ux-enterprise-audit/screenshots/tablet/ for app shell, overview/dashboard, customer review workspace, governance inbox, operations, evidence overview, and critical forms when feasible.
• T027 Capture optional mobile screenshots under docs/ui-ux-enterprise-audit/screenshots/mobile/ for the same high-risk surfaces when feasible.
• T028 Record screenshot blockers in docs/ui-ux-enterprise-audit/unresolved-pages.md for routes blocked by auth, missing data, provider connection, runtime errors, redirect loops, or manual inspection needs.
• T029 Do not add seeders, factories, fixtures, runtime routes, or UI changes to make screenshots easier.

Phase 5: Page Reports And Classification

• T030 Create one page report in docs/ui-ux-enterprise-audit/page-reports/ for each reviewed page using the page audit template.
• T031 [P] For each strategic candidate report, evaluate first-five-seconds test, productization review, enterprise readiness scores, top issues, target direction, and later spec recommendation.
• T032 [P] For each domain pattern report, document shared pattern fit, repeated information architecture problems, and whether a grouped follow-up spec is enough.
• T033 [P] For each design-system cleanup report, document table/form/state/action cleanup needs without requiring an individual mockup.
• T034 [P] For each internal/deprecated/hidden/manual-review route, document reason and do not make product-readiness claims.
• T035 Flag dangerous actions in relevant page reports, including restore, delete, approve exception, accept risk, close finding, rerun backup, export evidence, RBAC changes, disconnect integration, entitlement changes, workspace suspension, invites, and user removal.
• T036 Flag customer-facing or auditor-facing pages for customer-safe language, raw-data exposure, unsupported compliance claims, evidence clarity, and review-pack/export context.
• T037 Flag workspace/environment context ambiguity in page reports where shell, route, query, breadcrumbs, copy, or chips conflict.
• T038 Flag misleading status states where unknown, stale, pending, unconfirmed, not scanned, not reviewed, not connected, or not evaluated appear as healthy/successful.
• T039 Link every created page report back from docs/ui-ux-enterprise-audit/route-inventory.md.

Phase 6: Coverage Matrix And Follow-Up Grouping

• T040 Create docs/ui-ux-enterprise-audit/design-coverage-matrix.md with total routes discovered, pages reviewed, screenshots captured, strategic surfaces, domain pattern surfaces, cleanup surfaces, internal/deprecated surfaces, and manual-review counts.
• T041 Populate coverage by area in docs/ui-ux-enterprise-audit/design-coverage-matrix.md.
• T042 Populate coverage by archetype in docs/ui-ux-enterprise-audit/design-coverage-matrix.md.
• T043 Populate missing/unclear coverage and recommended next specs in docs/ui-ux-enterprise-audit/design-coverage-matrix.md.
• T044 Create docs/ui-ux-enterprise-audit/strategic-surfaces.md with P0/P1/P2 strategic surfaces, route, why strategic, current risk, and recommended target artifact.
• T045 Create docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md grouped by customer review workspace, governance inbox, operations, evidence, reviews, drift/findings, backup/restore, provider/onboarding, inventory, settings/admin, support/diagnostics, commercial/entitlements, auth/access, app shell/navigation, and global tables/forms/states.
• T046 Ensure grouped follow-up candidates state covered pages, shared problem, recommended later spec type, individual mockup need, domain-pattern sufficiency, and priority.

Phase 7: Ongoing Design Coverage Gate Baseline

• T047 Add the Ongoing Feature Design Coverage Gate guidance to docs/ui-ux-enterprise-audit/README.md.
• T048 Add the standard UI/UX Coverage Requirements checklist for later UI specs to docs/ui-ux-enterprise-audit/README.md or a template file.
• T049 Document the decision model for new strategic pages, normal domain pages, small admin/utility pages, modals/drawers/actions, and internal/manual-review features.
• T050 Ensure docs/ui-ux-enterprise-audit/route-inventory.md and design-coverage-matrix.md explain how future features update counts, pattern links, screenshot links, and unresolved entries.
• T056 Add UI/Productization Coverage as a durable principle in .specify/memory/constitution.md.
• T057 Add mandatory UI Surface Impact and UI/Productization Coverage blocks to .specify/templates/spec-template.md.
• T058 Add UI coverage planning, task, and checklist guardrails to .specify/templates/plan-template.md, .specify/templates/tasks-template.md, and .specify/templates/checklist-template.md.
• T059 Add the pre-implementation UI/Productization Coverage guardrail to .codex/prompts/speckit.implement.md and .github/agents/speckit.implement.agent.md.
• T060 Add a UI Surface Impact checkbox to .gitea/pull_request_template.md.
• T061 Add scripts/check-ui-productization-coverage and wire it into .gitea/workflows/test-pr-fast-feedback.yml.

Phase 8: Validation And Close-Out

• T051 Review the final diff and confirm no app runtime files under apps/platform/app/, apps/platform/config/, apps/platform/database/, apps/platform/resources/, apps/platform/routes/, or runtime tests were changed.
• T052 Run git diff --check and bash scripts/check-ui-productization-coverage HEAD from the repository root.
• T053 Record exact route/page count, pages reviewed, screenshot count, strategic surface count, unresolved page count, guardrail updates, and validation result for the final response.
• T054 Record that the work was browser audit / Markdown only and no runtime code was changed.
• T055 Record that the full suite was not run because no runtime code changed.

Non-Goals / Stop Conditions

• NT001 Do not modify runtime UI, Blade views, Filament resources/pages, Livewire components, routes, auth, policies, services, jobs, models, migrations, config, or tests.
• NT002 Do not rename runtime product concepts or change workspace/environment/tenant context behavior.
• NT003 Do not add packages, env vars, queues, scheduler changes, storage configuration, or deployment scripts.
• NT004 Do not create high-fidelity target mockups in Spec 323.
• NT005 Do not create one follow-up spec per small page.
• NT006 Do not present spec-only or conceptual UI as repo-verified product truth.
• NT007 Stop and update spec.md and plan.md before any application implementation becomes necessary.

Requirement Coverage Map

Requirement(s)	Task Coverage
FR-323-001, FR-323-018, FR-323-019	T007-T012, T047-T050
FR-323-022, FR-323-023, FR-323-024	T056-T061
FR-323-002	T013-T019
FR-323-003, FR-323-004, FR-323-005, FR-323-006	T020-T022, T040-T043
FR-323-007	T023-T028
FR-323-008, FR-323-013	T030-T039
FR-323-009	T040-T043
FR-323-010	T044
FR-323-011	T045-T046
FR-323-012	T022, T028
FR-323-014, FR-323-015, FR-323-016, FR-323-017	T035-T038
FR-323-020	T012
FR-323-021, NFR-323-005, NFR-323-007	T006, T029, T051, T054-T055, NT001-NT007
NFR-323-001, NFR-323-002, NFR-323-003, NFR-323-004	T008-T011, T020-T028, T030-T050
NFR-323-006	T052

Dependencies

1. Phase 1 must complete before audit artifacts are created.
2. Phase 2 must complete before discovery data is recorded.
3. Phase 3 must produce the first route inventory before browser screenshots and page reports are finalized.
4. Phase 4 screenshots can run in parallel with Phase 5 page reports once audit IDs are assigned.
5. Phase 6 depends on completed classifications from Phases 3 through 5.
6. Phase 7 depends on the final classification model used in the artifacts.
7. Phase 8 depends on all docs and screenshots being final.

MVP Scope

The minimum viable Spec 323 implementation is:

1. Required audit directory structure and templates.
2. Route inventory with every discovered page classified or unresolved.
3. Desktop screenshots for reachable strategic pages or documented blockers.
4. Page reports for reviewed pages.
5. Coverage matrix, strategic surfaces, grouped follow-up candidates, and unresolved pages.
6. Ongoing Design Coverage Gate documentation.
7. git diff --check passing with no runtime code changes.

Parallel Work Examples

Agent A: Route/file/navigation discovery and route-inventory.md.
Agent B: Browser screenshots for strategic/domain pages.
Agent C: Page reports for customer/review/evidence/governance surfaces.
Agent D: Coverage matrix, strategic-surfaces.md, and grouped-follow-up-candidates.md.

Parallel workers must not edit the same Markdown file at the same time.