TenantAtlas/specs/125-table-ux-standardization/tasks.md

# Tasks: Filament Table UX Standardization & List Consistency

**Input**: Design documents from `/specs/125-table-ux-standardization/`
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

**Tests**: Tests are REQUIRED for this runtime behavior change. Use Pest feature and guard coverage for critical list defaults, persisted table state, detail visibility, and query-risk exceptions.
**Operations**: No `OperationRun` work is required because this feature does not introduce long-running, remote, queued, or scheduled behavior.
**RBAC**: No new authorization behavior is introduced. Existing workspace and tenant isolation, capability checks, and destructive-action confirmation behavior must remain unchanged on all touched surfaces.
**Filament UI Action Surfaces**: This feature modifies Filament resources, relation managers, widgets, pages, and picker tables, but preserves their existing action architecture. Tasks must keep record inspection affordances, grouped bulk actions, and destructive confirmations intact.
**Filament UI UX-001**: This feature strengthens the table portions of UX-001 by standardizing empty states, search/sort behavior, and calm default visibility without changing create, edit, or view layouts.
**Badges**: Badge semantics must remain centralized through the existing `BadgeCatalog` and `BadgeRenderer` infrastructure; no ad-hoc status mappings are allowed.

**Organization**: Tasks are grouped by user story so each story remains independently testable.

## Phase 1: Setup (Shared Context)

**Purpose**: Align the rollout scope, target files, and existing test guardrails before touching runtime code.

- [X] T001 [P] Reconcile the rollout inventory, designated critical resource persistence set, and first-wave hotspot set in `specs/125-table-ux-standardization/spec.md`, `specs/125-table-ux-standardization/plan.md`, `specs/125-table-ux-standardization/research.md`, and `specs/125-table-ux-standardization/data-model.md` against the target table classes under `app/Filament/`, `app/Livewire/`, and `tests/Feature/`
- [X] T002 [P] Review existing list-surface guardrails in `tests/Feature/Guards/ActionSurfaceContractTest.php`, `tests/Feature/Guards/NoAdHocStatusBadgesTest.php`, and the current list regressions under `tests/Feature/Filament/` before changing table defaults

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Establish the shared standard, helper, and baseline test infrastructure that all user stories depend on.

**⚠️ CRITICAL**: No user story work should begin until this phase is complete.

- [X] T003 Create the internal table standard and future PR checklist in `docs/ui/filament-table-standard.md` using the approved Primary / Context / Detail, pagination, persistence, timestamp, null, and ID rules from `specs/125-table-ux-standardization/`
- [X] T004 [P] Introduce the narrow shared pagination profile helper in `app/Support/Filament/TablePaginationProfiles.php` for resource, relation manager, widget, picker, and custom-page page-size conventions without hiding per-surface search, sort, visibility, or empty-state behavior
- [X] T005 [P] Create baseline cross-surface regression coverage in `tests/Feature/Filament/TableStandardsBaselineTest.php` for explicit default sort, empty states, and calm default-column expectations on representative list surfaces
- [X] T006 [P] Create guard coverage in `tests/Feature/Guards/FilamentTableStandardsGuardTest.php` to block missing default-sort, missing empty-state, and missing designated-resource persistence declarations on in-scope standardized tables, with explicit documented-exception handling for approved no-search or query-risk surfaces

**Checkpoint**: The standard, pagination profiles, and baseline guardrails are ready; user story work can now proceed.

---

## Phase 3: User Story 1 - Scan Core Lists Predictably (Priority: P1) 🎯 MVP

**Goal**: Make the highest-value and most overloaded lists calm, sortable, and consistently empty-state-aware by default.

**Independent Test**: Open each first-wave critical list, verify a searchable and sortable primary identifier, confirm calm default columns with detail available on demand, and verify domain-specific empty-state behavior on empty datasets.

### Tests for User Story 1 ⚠️

- [X] T007 [P] [US1] Create critical-list regression coverage in `tests/Feature/Filament/TableStandardsCriticalListsTest.php` for tenant, policy, backup set, backup schedule, provider connection, finding, operation run, and backup items relation-manager defaults
- [X] T008 [P] [US1] Extend existing list regressions in `tests/Feature/Filament/TenantResourceIndexIsWorkspaceScopedTest.php`, `tests/Feature/Filament/PolicyListingTest.php`, `tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php`, and `tests/Feature/Findings/FindingsListDefaultsTest.php` with sortability, empty-state, and visible-column assertions

### Implementation for User Story 1

- [X] T009 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in `app/Filament/Resources/TenantResource.php`
- [X] T010 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in `app/Filament/Resources/PolicyResource.php`
- [X] T011 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in `app/Filament/Resources/BackupSetResource.php`
- [X] T012 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in `app/Filament/Resources/BackupScheduleResource.php`
- [X] T013 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in `app/Filament/Resources/ProviderConnectionResource.php` and `app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php`
- [X] T014 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in `app/Filament/Resources/FindingResource.php`
- [X] T015 [P] [US1] Standardize default sort, recency/status columns, detail visibility, and empty-state behavior in `app/Filament/Resources/OperationRunResource.php`
- [X] T016 [US1] Standardize the overloaded relation-backed list in `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php` without changing its existing row, bulk, and confirmation behavior

**Checkpoint**: The first-wave critical tables should now feel predictable and calmer by default while preserving existing actions and RBAC semantics.

---

## Phase 4: User Story 2 - Keep List Context Across Refresh (Priority: P2)

**Goal**: Persist search, sort, and filter state on key resource lists and align pagination behavior across table classes.

**Independent Test**: Apply search, sort, and filters on critical resource lists, refresh the page within the same session, and confirm the same list state remains active while approved page-size options stay consistent.

### Tests for User Story 2 ⚠️

- [X] T017 [P] [US2] Create resource-list persistence coverage in `tests/Feature/Filament/TableStatePersistenceTest.php` for search, sort, and filter state across refresh on `TenantResource`, `PolicyResource`, `BackupSetResource`, `BackupScheduleResource`, `ProviderConnectionResource`, `FindingResource`, and `OperationRunResource`
- [X] T018 [P] [US2] Extend scoped list coverage in `tests/Feature/Filament/TenantResourceIndexIsWorkspaceScopedTest.php`, `tests/Feature/Filament/PolicyListingTest.php`, `tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php`, and `tests/Feature/Findings/FindingsListFiltersTest.php` with resource pagination and persisted-state assertions

### Implementation for User Story 2

- [X] T019 [P] [US2] Apply native Filament search/sort/filter persistence and resource pagination profiles in `app/Filament/Resources/TenantResource.php`, `app/Filament/Resources/PolicyResource.php`, and `app/Filament/Resources/BackupSetResource.php`
- [X] T020 [P] [US2] Apply native Filament search/sort/filter persistence and resource pagination profiles in `app/Filament/Resources/BackupScheduleResource.php`, `app/Filament/Resources/ProviderConnectionResource.php`, `app/Filament/Resources/FindingResource.php`, and `app/Filament/Resources/OperationRunResource.php`
- [X] T021 [US2] Standardize pagination profiles across non-resource list surfaces in `app/Filament/Resources/PolicyResource/RelationManagers/VersionsRelationManager.php`, `app/Filament/Resources/BackupScheduleResource/RelationManagers/BackupScheduleOperationRunsRelationManager.php`, `app/Filament/Widgets/Dashboard/RecentDriftFindings.php`, `app/Filament/Widgets/Dashboard/RecentOperations.php`, `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, `app/Filament/System/Pages/Ops/Stuck.php`, `app/Filament/System/Pages/Directory/Tenants.php`, `app/Filament/System/Pages/Directory/Workspaces.php`, `app/Filament/System/Pages/Security/AccessLogs.php`, `app/Livewire/BackupSetPolicyPickerTable.php`, `app/Livewire/EntraGroupCachePickerTable.php`, and `app/Livewire/SettingsCatalogSettingsTable.php`

**Checkpoint**: Key resource lists should now preserve user context across refresh, and table-class pagination defaults should be consistent across the product.

---

## Phase 5: User Story 3 - Reveal Detail Only When Needed (Priority: P3)

**Goal**: Bring the remaining table surface into line on searchable primary identifiers, explicit default sort or documented exceptions, domain-specific empty states, hidden-by-default detail, timestamps, placeholders, identifiers, and query-safe exceptions.

**Independent Test**: Verify remaining resources, system pages, widgets, and picker tables expose a searchable primary identifier where appropriate, define an explicit default sort or documented exception, provide a domain-specific empty state, hide low-value technical detail by default, keep IDs readable without layout breakage, and document any approved no-search or query-risk exceptions.

### Tests for User Story 3 ⚠️

- [X] T022 [P] [US3] Create broad-rollout coverage in `tests/Feature/Filament/TableDetailVisibilityTest.php` for remaining resource, widget, page, and picker surfaces covering searchable primary identifiers where appropriate, explicit default sorts or documented exceptions, domain-specific empty states, detail visibility, timestamp rendering, placeholders, and identifier presentation
- [X] T023 [P] [US3] Add query-risk and documented-exception guard coverage in `tests/Feature/Guards/FilamentTableRiskExceptionsGuardTest.php` for computed and relation-backed columns that intentionally remain non-sortable or non-searchable, plus approved surfaces where search is explicitly documented as providing no user value

### Implementation for User Story 3

- [X] T024 [P] [US3] Standardize searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, calm defaults, toggle-hidden detail columns, timestamps, and null/ID rendering in `app/Filament/Resources/EntraGroupResource.php`, `app/Filament/Resources/AlertDeliveryResource.php`, `app/Filament/Resources/AlertRuleResource.php`, and `app/Filament/Resources/AlertDestinationResource.php`
- [X] T025 [P] [US3] Standardize searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, calm defaults, toggle-hidden detail columns, timestamps, and null/ID rendering in `app/Filament/Resources/BaselineProfileResource.php`, `app/Filament/Resources/BaselineSnapshotResource.php`, `app/Filament/Resources/InventoryItemResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, `app/Filament/Resources/ReviewPackResource.php`, and `app/Filament/Resources/Workspaces/WorkspaceResource.php`
- [X] T026 [P] [US3] Standardize remaining relation-manager surfaces for searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, and calm detail handling in `app/Filament/Resources/TenantResource/RelationManagers/TenantMembershipsRelationManager.php`, `app/Filament/Resources/Workspaces/RelationManagers/WorkspaceMembershipsRelationManager.php`, and `app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php`
- [X] T027 [P] [US3] Standardize custom pages, query-risk system pages, and widgets for searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, and calm detail handling in `app/Filament/Pages/InventoryCoverage.php`, `app/Filament/Pages/Monitoring/Operations.php`, `app/Filament/System/Pages/Directory/Tenants.php`, `app/Filament/System/Pages/Directory/Workspaces.php`, `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, `app/Filament/System/Pages/Ops/Stuck.php`, `app/Filament/System/Pages/Security/AccessLogs.php`, `app/Filament/System/Pages/RepairWorkspaceOwners.php`, `app/Filament/Widgets/Dashboard/RecentDriftFindings.php`, and `app/Filament/Widgets/Dashboard/RecentOperations.php`
- [X] T028 [US3] Standardize picker and selection tables for searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, and calm detail handling, then document surviving no-search and query-safe exceptions in `app/Livewire/BackupSetPolicyPickerTable.php`, `app/Livewire/EntraGroupCachePickerTable.php`, `app/Livewire/SettingsCatalogSettingsTable.php`, and `docs/ui/filament-table-standard.md`

**Checkpoint**: The broader table surface should now use the same default visibility, rendering, and documented-exception model as the first-wave critical lists.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Verify the full rollout, record a full-inventory compliance audit, format touched files, and complete manual QA before merge.

- [X] T029 [P] Run focused verification from `specs/125-table-ux-standardization/quickstart.md` with `vendor/bin/sail artisan test --compact tests/Feature/Filament/TableStandardsBaselineTest.php tests/Feature/Filament/TableStandardsCriticalListsTest.php tests/Feature/Filament/TableStatePersistenceTest.php tests/Feature/Filament/TableDetailVisibilityTest.php tests/Feature/Filament/TenantResourceIndexIsWorkspaceScopedTest.php tests/Feature/Filament/PolicyListingTest.php tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php tests/Feature/Findings/FindingsListDefaultsTest.php tests/Feature/Findings/FindingsListFiltersTest.php tests/Feature/Guards/FilamentTableStandardsGuardTest.php tests/Feature/Guards/FilamentTableRiskExceptionsGuardTest.php tests/Feature/Guards/ActionSurfaceContractTest.php tests/Feature/Guards/NoAdHocStatusBadgesTest.php`
- [X] T030 Run `vendor/bin/sail bin pint --dirty --format agent` after changing `app/Filament/`, `app/Livewire/`, `app/Support/Filament/`, `docs/ui/`, and `tests/Feature/`
- [X] T031 Produce the post-rollout audit in `docs/ui/filament-table-standard.md` or an adjacent rollout appendix by reconciling the full production table inventory against explicit default sort or documented exception, domain-specific empty states, default column-count targets, designated persistence surfaces, and approved no-search or query-risk exceptions
- [X] T032 [P] Complete manual QA from `specs/125-table-ux-standardization/quickstart.md` across first-wave and broad-rollout surfaces for persisted state, empty states, overflow handling, and documented no-search and query-risk exceptions before merge

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies; can start immediately.
- **Foundational (Phase 2)**: Depends on Setup completion; blocks all user stories.
- **User Story 1 (Phase 3)**: Depends on Foundational completion; this is the MVP slice.
- **User Story 2 (Phase 4)**: Depends on Foundational completion and should follow User Story 1 because it touches the same critical resource files.
- **User Story 3 (Phase 5)**: Depends on Foundational completion and is safest after User Stories 1 and 2 establish the critical resource baseline.
- **Polish (Phase 6)**: Depends on completion of the desired user stories and closes with the final inventory audit.

### User Story Dependencies

- **User Story 1 (P1)**: No dependency on other stories; delivers the first high-value standardization slice.
- **User Story 2 (P2)**: Can be tested independently, but should land after US1 because it modifies the same critical resource tables to add persistence and shared pagination behavior.
- **User Story 3 (P3)**: Can be tested independently, but should land after the critical-list baseline is stable so broad-rollout regressions are easier to isolate.

### Within Each User Story

- Test tasks should be added first and observed failing before implementation is considered complete.
- Resource and relation-manager updates should preserve existing record inspection affordances, row actions, bulk actions, and destructive confirmations.
- Query-risk surfaces should document exceptions before adding new sorts or searches to computed or relation-backed columns.
- Shared pagination profiles should be reused where they reduce mechanical duplication, but domain-specific table logic must remain explicit in each `table()` definition.

### Parallel Opportunities

- `T001` and `T002` can run in parallel.
- `T004`, `T005`, and `T006` can run in parallel once the foundational direction is agreed.
- `T007` and `T008` can run in parallel because they touch different test files.
- `T009` through `T015` can run in parallel because they touch different resource files.
- `T017` and `T018` can run in parallel because they touch different test files.
- `T019` and `T020` can run in parallel because they split the critical resource set across different files.
- `T022` and `T023` can run in parallel because they touch different test files.
- `T024`, `T025`, `T026`, and `T027` can run in parallel because they address different groups of surfaces.
- `T029` and `T032` can run in parallel once implementation is complete.

---

## Parallel Example: User Story 1

```bash
# Split first-wave critical resources across separate files:
Task: "T009 [US1] Standardize TenantResource in app/Filament/Resources/TenantResource.php"
Task: "T010 [US1] Standardize PolicyResource in app/Filament/Resources/PolicyResource.php"
Task: "T011 [US1] Standardize BackupSetResource in app/Filament/Resources/BackupSetResource.php"
Task: "T012 [US1] Standardize BackupScheduleResource in app/Filament/Resources/BackupScheduleResource.php"
Task: "T013 [US1] Standardize ProviderConnectionResource in app/Filament/Resources/ProviderConnectionResource.php and app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php"
Task: "T014 [US1] Standardize FindingResource in app/Filament/Resources/FindingResource.php"
Task: "T015 [US1] Standardize OperationRunResource in app/Filament/Resources/OperationRunResource.php"
```

---

## Parallel Example: User Story 2

```bash
# Split persistence rollout across the critical resource files:
Task: "T019 [US2] Apply persistence and resource pagination profiles in app/Filament/Resources/TenantResource.php, app/Filament/Resources/PolicyResource.php, and app/Filament/Resources/BackupSetResource.php"
Task: "T020 [US2] Apply persistence and resource pagination profiles in app/Filament/Resources/BackupScheduleResource.php, app/Filament/Resources/ProviderConnectionResource.php, app/Filament/Resources/FindingResource.php, and app/Filament/Resources/OperationRunResource.php"
```

---

## Parallel Example: User Story 3

```bash
# Split the broad rollout by surface group:
Task: "T024 [US3] Standardize remaining alert and group resources"
Task: "T025 [US3] Standardize baseline, inventory, policy-version, review-pack, and workspace resources"
Task: "T026 [US3] Standardize remaining relation managers"
Task: "T027 [US3] Standardize custom pages, system pages, and widgets"
```

---

## Implementation Strategy

### MVP First (User Story 1 Only)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate the critical list surfaces independently.
5. Demo or review the first-wave standard before layering persistence and broad-rollout work.

### Incremental Delivery

1. Establish the standard, pagination profiles, and baseline guards.
2. Ship the first-wave critical lists in US1.
3. Add persisted list state and aligned pagination in US2.
4. Finish the remaining surface rollout and documented exceptions in US3.
5. Close with focused Sail tests, a full inventory audit, Pint, and manual QA.

### Suggested MVP Scope

- Deliver through **Phase 3 / User Story 1** for the first merge candidate.
- Defer persisted-state rollout and broad-surface cleanup until the critical list standards are accepted.

---

## Notes

- All tasks follow the required checklist format: checkbox, task ID, optional `[P]`, required story label for story phases, and exact file paths.
- No migrations, queue jobs, Graph integrations, or new authorization rules are part of this task list.
- The action-surface contract remains in force: no task should remove record inspection affordances, grouped bulk actions, or destructive confirmations from existing list surfaces.