# Tasks: Filter UX Standardization

**Input**: Design documents from `/specs/126-filter-ux-standardization/`
**Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/filament-filter-state.openapi.yaml`, `quickstart.md`

**Tests**: Required. This feature changes runtime Filament table behavior, so Pest and Livewire coverage must be updated for persistence, filter behavior, guard enforcement, and scope safety.
**Operations**: No new `OperationRun` lifecycle or operational workflow work is introduced; only existing `OperationRun` table filter-label alignment and related test coverage are in scope.
**RBAC**: Authorization semantics do not change, but tasks must preserve tenant/workspace scope boundaries and include positive and negative scope regression coverage on representative lists.
**Filament UI Action Surfaces**: The feature changes list-table filtering only. The task list includes explicit work to keep the spec’s UI Action Matrix accurate for the changed surfaces while preserving existing action surfaces.
**Filament UI UX-001**: The feature affects list-table filtering and persistence only. Empty-state, create/edit, and view layouts remain unchanged unless a changed surface requires an explicit note.
**Badges**: Status label sourcing must continue to rely on centralized domain vocabularies; no ad-hoc status mapping may be introduced.

**Organization**: Tasks are grouped by user story so each story can be implemented and tested independently.

## Phase 1: Setup (Shared Implementation Alignment)

**Purpose**: Lock the concrete rollout surface inventory and shared implementation targets before code changes start.

- [X] T001 Review the concrete rollout targets and current list-page entry points in `app/Filament/Resources/FindingResource.php`, `app/Filament/Resources/InventoryItemResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, `app/Filament/Resources/RestoreRunResource.php`, `app/Filament/Resources/AlertDeliveryResource.php`, `app/Filament/Resources/EntraGroupResource.php`, `app/Filament/Resources/BaselineProfileResource.php`, and `app/Filament/Resources/OperationRunResource.php`
- [X] T002 Confirm centralized option-source inputs in `app/Models/Finding.php`, `app/Models/AlertDelivery.php`, `app/Support/Badges/BadgeCatalog.php`, and `app/Support/Baselines/BaselineProfileStatus.php` before implementing shared filter helpers

---

## Phase 2: Foundational (Blocking Prerequisites)

**Purpose**: Shared support and enforcement that all user stories depend on.

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

- [X] T003 Create thin shared filter support in `app/Support/Filament/FilterOptionCatalog.php` and `app/Support/Filament/FilterPresets.php` for centralized option sourcing plus native archived/date-range presets
- [X] T004 [P] Extend reusable Tier 1–2 surface inventories and helper assertions in `tests/Feature/Guards/FilamentTableStandardsGuardTest.php` to prepare for persistence, archived-filter, and centralized-status guard coverage
- [X] T005 [P] Extend the shared Livewire persistence harness in `tests/Feature/Filament/TableStatePersistenceTest.php` so additional resource list page components can be covered without duplicating setup logic

**Checkpoint**: Shared filter support and reusable test scaffolding are ready.

---

## Phase 3: User Story 1 - Keep Investigation Context (Priority: P1) 🎯 MVP

**Goal**: Ensure important Tier 1–2 resource lists preserve filter, search, and sort state across refresh and navigation.

**Independent Test**: Apply search, sort, and filters on each newly covered in-scope list, remount the component, and confirm the same state persists without widening workspace or tenant scope.

### Tests for User Story 1

- [X] T006 [P] [US1] Extend persistence coverage in `tests/Feature/Filament/TableStatePersistenceTest.php` for `ListInventoryItems`, `ListPolicyVersions`, `ListRestoreRuns`, `ListAlertDeliveries`, and `ListEntraGroups`
- [X] T007 [P] [US1] Add representative scope-safe persistence regression coverage in `tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php` and `tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php`

### Implementation for User Story 1

- [X] T008 [P] [US1] Add `persistFiltersInSession()`, `persistSearchInSession()`, and `persistSortInSession()` to `app/Filament/Resources/InventoryItemResource.php` and `app/Filament/Resources/EntraGroupResource.php`
- [X] T009 [P] [US1] Add `persistFiltersInSession()`, `persistSearchInSession()`, and `persistSortInSession()` to `app/Filament/Resources/PolicyVersionResource.php` and `app/Filament/Resources/RestoreRunResource.php`
- [X] T010 [US1] Add `persistFiltersInSession()`, `persistSearchInSession()`, and `persistSortInSession()` to `app/Filament/Resources/AlertDeliveryResource.php` while preserving workspace-context entitlement safety
- [X] T011 [US1] Expand persistence enforcement in `tests/Feature/Guards/FilamentTableStandardsGuardTest.php` for all Tier 1–2 filtered resource lists

**Checkpoint**: Important resource lists retain investigation context across remounts and guard enforcement covers the expanded persistence set.

---

## Phase 4: User Story 2 - Filter Similar Lists the Same Way (Priority: P2)

**Goal**: Standardize archived visibility, centralized status sourcing, and missing date-range or essential filters across the highest-value Tier 1–2 lists.

**Independent Test**: Verify that changed lists expose the expected filters, that filters apply and clear correctly, and that date-range indicators and archived semantics are consistent across comparable surfaces.

### Tests for User Story 2

- [X] T012 [P] [US2] Add Findings filter tests covering filter application, clearing/reset, multi-filter composition, default behavior, date-range behavior, and representative workspace/tenant scope safety in `tests/Feature/Findings/FindingsListFiltersTest.php` and `tests/Feature/Findings/FindingsListDefaultsTest.php`
- [X] T013 [P] [US2] Add AlertDelivery filter tests covering filter application, clearing/reset, multi-filter composition, default behavior, date-range behavior, and representative workspace/tenant scope safety in `tests/Feature/Alerts/AlertDeliveryDeepLinkFiltersTest.php` and `tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php`
- [X] T014 [P] [US2] Add `OperationRunResource` filter behavior tests covering filter application, clearing/reset, multi-filter composition, and representative workspace/tenant scope safety in `tests/Feature/Filament/OperationRunListFiltersTest.php`
- [X] T015 [P] [US2] Add filter-application, clearing/reset, and composition coverage in `tests/Feature/Filament/PolicyVersionListFiltersTest.php` and `tests/Feature/Filament/RestoreRunListFiltersTest.php`
- [X] T016 [P] [US2] Add filter-application, clearing/reset, and scope-safe behavior coverage in `tests/Feature/Filament/InventoryItemListFiltersTest.php` and `tests/Feature/Filament/BaselineProfileListFiltersTest.php`

### Implementation for User Story 2

- [X] T017 [US2] Wire `app/Support/Filament/FilterOptionCatalog.php` into `app/Filament/Resources/FindingResource.php` and `app/Filament/Resources/AlertDeliveryResource.php` for centralized status option sourcing
- [X] T018 [US2] Add native date-range filters with `indicateUsing()` in `app/Filament/Resources/FindingResource.php` and `app/Filament/Resources/AlertDeliveryResource.php` using `app/Support/Filament/FilterPresets.php`
- [X] T019 [US2] Add status, outcome, date-range, and standard archived filtering in `app/Filament/Resources/RestoreRunResource.php`
- [X] T020 [US2] Add policy type, platform, `captured_at` date-range, and standard archived filtering in `app/Filament/Resources/PolicyVersionResource.php`
- [X] T021 [US2] Add platform and sync-freshness filtering in `app/Filament/Resources/InventoryItemResource.php` and a status filter in `app/Filament/Resources/BaselineProfileResource.php`
- [X] T022 [US2] Update the operation-type filter options in `app/Filament/Resources/OperationRunResource.php` to use `OperationCatalog` labels consistently with the filter standard
- [X] T030 [P] [US2] Add follow-up filter behavior coverage in `tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php` and `tests/Feature/Filament/BaselineSnapshotListFiltersTest.php`
- [X] T031 [US2] Add type, restore-mode, platform filters and session persistence to `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`
- [X] T032 [US2] Add baseline, state, `captured_at` filters and session persistence to `app/Filament/Resources/BaselineSnapshotResource.php`, and extend persistence enforcement in `tests/Feature/Guards/FilamentTableStandardsGuardTest.php` and `tests/Feature/Filament/TableStatePersistenceTest.php`

**Checkpoint**: The highest-value Tier 1–2 lists share predictable archived semantics, date-range behavior, and centralized status labels.

---

## Phase 5: User Story 3 - Prevent Filter Drift (Priority: P3)

**Goal**: Keep the new filter standard enforceable so future list changes cannot silently regress persistence, archived filtering, or centralized status sourcing.

**Independent Test**: Introduce a deliberate regression locally, run the targeted guard suite, and confirm it fails with actionable output pointing to the violating resource.

### Tests for User Story 3

- [X] T023 [P] [US3] Extend `tests/Feature/Guards/FilamentTableStandardsGuardTest.php` to assert standard archived filter usage and prioritized centralized status sourcing on in-scope resources
- [X] T024 [P] [US3] Add composed-filter scope regression coverage in `tests/Feature/ProviderConnections/TenantFilterOverrideTest.php` and `tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php`

### Implementation for User Story 3

- [X] T025 [US3] Adopt `app/Support/Filament/FilterPresets.php` in `app/Filament/Resources/PolicyVersionResource.php` and `app/Filament/Resources/RestoreRunResource.php` so repeated archived/date-range patterns stay mechanically consistent
- [X] T026 [US3] Record any approved query-risk or transitional status-source exceptions in `specs/126-filter-ux-standardization/spec.md`, `specs/126-filter-ux-standardization/plan.md`, and `specs/126-filter-ux-standardization/research.md`

**Checkpoint**: The filter standard is guarded in CI and any remaining exceptions are explicit rather than accidental.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final verification, formatting, and manual validation across stories.

- [X] T027 [P] Run focused Pest coverage for `tests/Feature/Guards/FilamentTableStandardsGuardTest.php`, `tests/Feature/Filament/TableStatePersistenceTest.php`, `tests/Feature/Findings/FindingsListFiltersTest.php`, `tests/Feature/Findings/FindingsListDefaultsTest.php`, `tests/Feature/Alerts/AlertDeliveryDeepLinkFiltersTest.php`, `tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php`, `tests/Feature/Filament/OperationRunListFiltersTest.php`, `tests/Feature/Filament/PolicyVersionListFiltersTest.php`, `tests/Feature/Filament/RestoreRunListFiltersTest.php`, `tests/Feature/Filament/InventoryItemListFiltersTest.php`, and `tests/Feature/Filament/BaselineProfileListFiltersTest.php`
- [X] T028 Run formatting on changed files with `vendor/bin/sail bin pint --dirty --format agent`
- [ ] T029 [P] Validate the manual QA scenarios in `specs/126-filter-ux-standardization/quickstart.md` against the changed resource lists and record any follow-up exceptions in `specs/126-filter-ux-standardization/research.md`

---

## 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)**: Starts after Foundational completion; represents the MVP slice.
- **User Story 2 (Phase 4)**: Starts after Foundational completion; can overlap with US1 if staffing allows, but is lower priority.
- **User Story 3 (Phase 5)**: Depends on the shared support from Foundational and should follow the main persistence and filter implementations so guards reflect the final standardized state.
- **Polish (Phase 6)**: Depends on all desired user stories being complete.

### User Story Dependencies

- **User Story 1 (P1)**: Depends only on Foundational work.
- **User Story 2 (P2)**: Depends on Foundational work and reuses the shared support from `app/Support/Filament/FilterOptionCatalog.php` and `app/Support/Filament/FilterPresets.php`.
- **User Story 3 (P3)**: Depends on Foundational work and should be completed after the main US1/US2 resource changes so static guard coverage matches reality.

### Within Each User Story

- Write or extend tests first and confirm they fail before implementing behavior changes.
- Shared support before resource-table rewrites.
- Resource-table changes before guard finalization.
- Functional verification before polish.

### Parallel Opportunities

- `T004` and `T005` can run in parallel once `T003` is scoped.
- In US1, `T006` and `T007` can run in parallel, as can `T008` and `T009`.
- In US2, `T012` through `T016` can run in parallel, followed by surface-specific implementation tasks split across resources.
- In US3, `T023` and `T024` can run in parallel.
- In Polish, `T027` and `T029` can run in parallel after implementation is complete.

---

## Parallel Example: User Story 1

```bash
# Launch persistence tests together:
Task: "Extend tests/Feature/Filament/TableStatePersistenceTest.php for the five new resource lists"
Task: "Add scope-safe persistence regression coverage in tests/Feature/Rbac/InventoryItemResourceAuthorizationTest.php and tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php"

# Launch resource persistence updates together:
Task: "Add the persistence trio to app/Filament/Resources/InventoryItemResource.php and app/Filament/Resources/EntraGroupResource.php"
Task: "Add the persistence trio to app/Filament/Resources/PolicyVersionResource.php and app/Filament/Resources/RestoreRunResource.php"
```

---

## Parallel Example: User Story 2

```bash
# Launch focused filter tests together:
Task: "Extend findings filter tests in tests/Feature/Findings/FindingsListFiltersTest.php and tests/Feature/Findings/FindingsListDefaultsTest.php"
Task: "Extend alert delivery filter tests in tests/Feature/Alerts/AlertDeliveryDeepLinkFiltersTest.php and tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php"
Task: "Add policy version and restore run list filter tests in tests/Feature/Filament/PolicyVersionListFiltersTest.php and tests/Feature/Filament/RestoreRunListFiltersTest.php"
Task: "Add inventory item and baseline profile list filter tests in tests/Feature/Filament/InventoryItemListFiltersTest.php and tests/Feature/Filament/BaselineProfileListFiltersTest.php"

# Launch resource implementations by surface group:
Task: "Add finding and alert delivery centralized status/date-range filters in app/Filament/Resources/FindingResource.php and app/Filament/Resources/AlertDeliveryResource.php"
Task: "Add restore run and policy version essential filters in app/Filament/Resources/RestoreRunResource.php and app/Filament/Resources/PolicyVersionResource.php"
Task: "Add inventory item and baseline profile essential filters in app/Filament/Resources/InventoryItemResource.php and app/Filament/Resources/BaselineProfileResource.php"
```

---

## 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 persistence behavior and expanded persistence guards.

### Incremental Delivery

1. Deliver US1 first to close the most painful operator gap: lost list context.
2. Deliver US2 next to standardize the highest-value filters and date-range behavior.
3. Deliver US3 last to lock the standard with stronger guard coverage and documented exceptions.
4. Finish with focused tests, formatting, and manual QA.
