TenantAtlas/specs/126-filter-ux-standardization/tasks.md

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.

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

• 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
• 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
• 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

• T006 [P] [US1] Extend persistence coverage in tests/Feature/Filament/TableStatePersistenceTest.php for ListInventoryItems, ListPolicyVersions, ListRestoreRuns, ListAlertDeliveries, and ListEntraGroups
• 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

• T008 [P] [US1] Add persistFiltersInSession(), persistSearchInSession(), and persistSortInSession() to app/Filament/Resources/InventoryItemResource.php and app/Filament/Resources/EntraGroupResource.php
• T009 [P] [US1] Add persistFiltersInSession(), persistSearchInSession(), and persistSortInSession() to app/Filament/Resources/PolicyVersionResource.php and app/Filament/Resources/RestoreRunResource.php
• T010 [US1] Add persistFiltersInSession(), persistSearchInSession(), and persistSortInSession() to app/Filament/Resources/AlertDeliveryResource.php while preserving workspace-context entitlement safety
• 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

• 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
• 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
• 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
• T015 [P] [US2] Add filter-application, clearing/reset, and composition coverage in tests/Feature/Filament/PolicyVersionListFiltersTest.php and tests/Feature/Filament/RestoreRunListFiltersTest.php
• 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

• 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
• 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
• T019 [US2] Add status, outcome, date-range, and standard archived filtering in app/Filament/Resources/RestoreRunResource.php
• T020 [US2] Add policy type, platform, captured_at date-range, and standard archived filtering in app/Filament/Resources/PolicyVersionResource.php
• T021 [US2] Add platform and sync-freshness filtering in app/Filament/Resources/InventoryItemResource.php and a status filter in app/Filament/Resources/BaselineProfileResource.php
• T022 [US2] Update the operation-type filter options in app/Filament/Resources/OperationRunResource.php to use OperationCatalog labels consistently with the filter standard

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

• T023 [P] [US3] Extend tests/Feature/Guards/FilamentTableStandardsGuardTest.php to assert standard archived filter usage and prioritized centralized status sourcing on in-scope resources
• 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

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

• 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
• 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

# 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

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