# Tasks: Backup Quality Truth Surfaces **Input**: Design documents from `/specs/176-backup-quality-truth/` **Prerequisites**: `plan.md` (required), `spec.md` (required for user stories), `research.md`, `data-model.md`, `contracts/`, `quickstart.md` **Tests**: Tests are REQUIRED for this feature. Use focused Pest coverage in existing backup, version, restore-selection, and RBAC suites, plus new backup-quality tests under `tests/Feature/Filament/`, `tests/Feature/Rbac/`, and `tests/Unit/Support/BackupQuality/`. **Operations**: This feature introduces no new `OperationRun`, no queued or scheduled work, and no new audit event family. Work is limited to read-first quality truth on existing backup, version, and restore-selection surfaces. **RBAC**: Existing tenant membership, capability-registry usage, and `404` vs `403` behavior must remain unchanged across `/admin/t/{tenant}/backup-sets/...`, `/admin/t/{tenant}/policy-versions/...`, and `/admin/t/{tenant}/restore-runs/create`. Users with `TENANT_VIEW` must see backup-quality truth on read surfaces even when restore actions remain unavailable. **Operator Surfaces**: Backup-set list and detail, backup-items relation rows, policy-version list and detail, and restore wizard step 1 and step 2 must show backup-quality truth before diagnostics or later restore-safety conclusions. Quality copy must remain distinct from lifecycle, restore readiness, and tenant recoverability claims. **Filament UI Action Surfaces**: No new primary inspect model, redundant View action, or destructive-action placement is introduced. Existing archive, restore, force-delete, remove, and bulk actions remain confirmation-gated and server-authorized. **Filament UI UX-001**: This feature keeps the existing Filament list, relation-manager, infolist, enterprise-detail, and wizard layouts. New quality sections must be summary-first and diagnostics-second. **Badges**: Snapshot completeness must continue to use centralized badge semantics through `app/Support/Badges/Domains/PolicySnapshotModeBadge.php`. Any additional quality wording must come from the shared backup-quality layer rather than page-local mappings. **Organization**: Tasks are grouped by user story so each story can be implemented and validated as an independent increment after the shared backup-quality scaffolding is in place. ## Phase 1: Setup (Shared Backup-Quality Scaffolding) **Purpose**: Add the narrow derived backup-quality layer and base test scaffolding used by every story. - [X] T001 Create the shared backup-quality resolver and summary types in `app/Support/BackupQuality/BackupQualityResolver.php` and `app/Support/BackupQuality/BackupQualitySummary.php` - [X] T002 [P] Add unit test scaffolding for resolver rules and aggregate summaries in `tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php` and `tests/Unit/Support/BackupQuality/BackupSetQualitySummaryTest.php` - [X] T003 Add metadata convenience helpers for item evidence in `app/Models/BackupItem.php` and mirror them in `app/Models/PolicyVersion.php` only if resolver wiring still leaves justified duplication there - [X] T004 [P] Extend metadata semantics regression coverage in `tests/Unit/BackupItemTest.php` and `tests/Unit/AssignmentBackupServiceTest.php` --- ## Phase 2: Foundational (Blocking Shared Wiring) **Purpose**: Wire the shared backup-quality contract into the existing Filament seams before any story-specific surface work begins. **⚠️ CRITICAL**: No user story work should begin until this phase is complete. - [X] T005 Thread shared backup-quality loading and aggregation hooks through `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, and `app/Filament/Resources/RestoreRunResource.php` - [X] T006 [P] Reuse centralized snapshot-mode and summary copy seams in `app/Support/Badges/Domains/PolicySnapshotModeBadge.php` and `app/Support/BackupQuality/BackupQualitySummary.php` - [X] T007 [P] Add shared mixed-signal, integrity-warning, and unknown-quality regression coverage in `tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php` and `tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php` **Checkpoint**: Backup, version, and restore-selection resources can now consume one shared backup-quality contract. --- ## Phase 3: User Story 1 - Judge Backup Sets Early (Priority: P1) 🎯 MVP **Goal**: Let operators distinguish stored backup sets from degraded recovery input within one scan of the list or detail surface. **Independent Test**: Load backup-set list and detail pages with full-quality, mixed-quality, and metadata-only fixtures and verify lifecycle truth stays separate from a default-visible quality summary. ### Tests for User Story 1 - [X] T008 [P] [US1] Add backup-set list truth coverage for full, mixed, metadata-only, and archived sets in `tests/Feature/Filament/BackupQualityTruthSurfaceTest.php` - [X] T009 [P] [US1] Extend summary-first backup-set detail assertions to cover archived parity and integrity-warning counts in `tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php` ### Implementation for User Story 1 - [X] T010 [US1] Add compact backup-quality summary columns and row copy to `app/Filament/Resources/BackupSetResource.php` - [X] T011 [US1] Add a default-visible quality summary section with integrity-warning counts, next-action guidance, and contextual related links that stay out of the header in `app/Filament/Resources/BackupSetResource.php` - [X] T012 [US1] Ensure backup-set quality summaries use aggregated item facts without new N+1 queries in `app/Support/BackupQuality/BackupQualityResolver.php` and `app/Filament/Resources/BackupSetResource.php` - [X] T013 [US1] Run the focused backup-set truth pack in `tests/Feature/Filament/BackupQualityTruthSurfaceTest.php` and `tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php` **Checkpoint**: Backup-set list and detail now expose input quality early without implying restore safety. --- ## Phase 4: User Story 2 - Inspect Item and Version Strength (Priority: P2) **Goal**: Make item-level and version-level payload quality explicit instead of forcing operators to infer it from disabled actions or hidden metadata. **Independent Test**: Load backup-items and policy-versions surfaces with full, metadata-only, assignment-fetch-failed, orphaned-assignment, and not-applicable fixtures and verify each surface renders explicit quality truth at scan speed. ### Tests for User Story 2 - [X] T014 [P] [US2] Extend backup-item relation truth coverage for snapshot mode, assignment failures, orphaned assignments, non-failure capture reasons, and inspect-next-step cues in `tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php` - [X] T015 [P] [US2] Add policy-version quality list and detail coverage for full, degraded, integrity-warning, and archived versions in `tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php` and `tests/Feature/Filament/PolicyVersionTest.php` - [X] T016 [P] [US2] Add regression coverage that quality truth remains visible independently from restore action gating in `tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php` and `tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php` ### Implementation for User Story 2 - [X] T017 [US2] Add per-item snapshot mode, assignment-quality signals, and inspect-detail next-step cues to `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php` - [X] T018 [US2] Add scan-speed snapshot mode, integrity-warning visibility, stronger-version or open-detail cues, and a single empty-state CTA to the table schema in `app/Filament/Resources/PolicyVersionResource.php` - [X] T019 [US2] Add an explicit backup-quality infolist section with integrity-warning truth and non-overclaiming guidance in `app/Filament/Resources/PolicyVersionResource.php` - [X] T020 [US2] Remove page-local quality derivation from item and version surfaces by routing them through `app/Support/BackupQuality/BackupQualityResolver.php`, `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`, and `app/Filament/Resources/PolicyVersionResource.php` - [X] T021 [US2] Run the focused item and version truth pack in `tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php`, `tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php`, `tests/Feature/Filament/PolicyVersionTest.php`, and `tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php` **Checkpoint**: Backup items and policy versions now expose quality truth directly where operators inspect them. --- ## Phase 5: User Story 3 - Select Restore Inputs With Early Warning (Priority: P3) **Goal**: Show weak backup sets and items at the first restore-selection step, before later restore-safety checks or preview work begins. **Independent Test**: Open the restore wizard with degraded backup-set and backup-item fixtures and verify step 1 and step 2 expose input quality before any risk-check output is shown. ### Tests for User Story 3 - [X] T022 [P] [US3] Add step-1 degraded backup-set hint coverage in `tests/Feature/Filament/RestoreSelectionQualityTruthTest.php` - [X] T023 [P] [US3] Extend pre-risk-check item-quality assertions in `tests/Feature/Filament/RestoreItemSelectionTest.php` and `tests/Feature/RestoreRiskChecksWizardTest.php` ### Implementation for User Story 3 - [X] T024 [US3] Add backup-set quality summaries to step-1 option labels and helper text in `app/Filament/Resources/RestoreRunResource.php` - [X] T025 [US3] Add item-level snapshot mode and assignment-quality descriptions to restore item option data in `app/Filament/Resources/RestoreRunResource.php` - [X] T026 [US3] Preserve the backup-quality versus restore-safety claim boundary in `app/Filament/Resources/RestoreRunResource.php` and `app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php` - [X] T027 [US3] Run the focused restore-selection truth pack in `tests/Feature/Filament/RestoreSelectionQualityTruthTest.php`, `tests/Feature/Filament/RestoreItemSelectionTest.php`, and `tests/Feature/RestoreRiskChecksWizardTest.php` **Checkpoint**: Restore selection now exposes degraded input before later restore-safety logic runs. --- ## Phase 6: User Story 4 - Preserve Truth Under RBAC Boundaries (Priority: P4) **Goal**: Keep backup-quality truth visible to read-only tenant viewers while preserving existing restore and mutation restrictions plus deny-as-not-found behavior. **Independent Test**: Sign in as a tenant member with `TENANT_VIEW` but without restore capability and verify backup-set and policy-version surfaces still show quality truth, while non-members still receive `404` and in-scope users without mutation capability still receive `403` on execution. ### Tests for User Story 4 - [X] T028 [P] [US4] Add tenant-view visibility coverage for backup-set, backup-item relation rows, and policy-version quality truth in `tests/Feature/Rbac/BackupQualityVisibilityTest.php` - [X] T029 [P] [US4] Extend deny-as-not-found and missing-capability regressions for backup and restore entry points in `tests/Feature/Filament/BackupSetUiEnforcementTest.php`, `tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php`, `tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php`, and `tests/Feature/Rbac/PolicyVersionsRestoreToIntuneUiEnforcementTest.php` ### Implementation for User Story 4 - [X] T030 [US4] Adjust quality-section visibility so read surfaces and backup-item relation rows remain available to `TENANT_VIEW` users in `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php`, and `app/Filament/Resources/PolicyVersionResource.php` - [X] T031 [US4] Preserve `404` vs `403` semantics around restore-linked quality hints in `app/Filament/Resources/RestoreRunResource.php` and `app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php` - [X] T032 [US4] Run the focused RBAC truth pack in `tests/Feature/Rbac/BackupQualityVisibilityTest.php`, `tests/Feature/Filament/BackupSetUiEnforcementTest.php`, `tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php`, `tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php`, and `tests/Feature/Rbac/PolicyVersionsRestoreToIntuneUiEnforcementTest.php` **Checkpoint**: Quality truth remains visible under read-only permissions without weakening authorization boundaries. --- ## Phase 7: Polish & Cross-Cutting Concerns **Purpose**: Final consistency, cleanup, formatting, and focused verification across all stories. - [X] T033 [P] Review and align operator-facing backup-quality copy and next-action wording in `app/Support/BackupQuality/BackupQualitySummary.php`, `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, and `app/Filament/Resources/RestoreRunResource.php` - [X] T034 Remove dead fallback derivation and duplicate helper logic left after story implementation in `app/Support/BackupQuality/BackupQualityResolver.php`, `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, and `app/Filament/Resources/RestoreRunResource.php` - [X] T035 Run formatting with `vendor/bin/sail bin pint --dirty --format agent` for `app/Support/BackupQuality/BackupQualityResolver.php`, `app/Filament/Resources/BackupSetResource.php`, `app/Filament/Resources/PolicyVersionResource.php`, `app/Filament/Resources/RestoreRunResource.php`, and `tests/Feature/Filament/BackupQualityTruthSurfaceTest.php` - [X] T036 Run the focused verification pack from `specs/176-backup-quality-truth/quickstart.md` against `tests/Feature/Filament/BackupQualityTruthSurfaceTest.php`, `tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php`, `tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php`, `tests/Feature/Filament/BackupSetUiEnforcementTest.php`, `tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php`, `tests/Feature/Filament/PolicyVersionTest.php`, `tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php`, `tests/Feature/Filament/RestoreSelectionQualityTruthTest.php`, `tests/Feature/Filament/RestoreItemSelectionTest.php`, `tests/Feature/RestoreRiskChecksWizardTest.php`, `tests/Feature/Rbac/BackupQualityVisibilityTest.php`, `tests/Feature/Rbac/BackupItemsRelationManagerUiEnforcementTest.php`, `tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php`, `tests/Feature/Rbac/PolicyVersionsRestoreToIntuneUiEnforcementTest.php`, `tests/Unit/Support/BackupQuality/BackupQualityResolverTest.php`, `tests/Unit/Support/BackupQuality/BackupSetQualitySummaryTest.php`, `tests/Unit/AssignmentBackupServiceTest.php`, and `tests/Unit/BackupItemTest.php` - [ ] T037 Run the manual validation pass in `specs/176-backup-quality-truth/quickstart.md` for backup-set, policy-version, restore-selection, and RBAC truth surfaces --- ## Dependencies & Execution Order ### Phase Dependencies - **Setup (Phase 1)**: Starts immediately and establishes the shared backup-quality namespace and test scaffolding. - **Foundational (Phase 2)**: Depends on Setup and blocks all story work until existing Filament resources consume the shared resolver and summary contract. - **User Story 1 (Phase 3)**: Starts after Foundational and delivers the MVP truth surface on backup-set list and detail pages. - **User Story 2 (Phase 4)**: Starts after Foundational and can proceed alongside User Story 1 once the shared resolver contract is stable. - **User Story 3 (Phase 5)**: Starts after User Story 1 and User Story 2 because restore selection reuses both aggregate backup-set truth and item-level quality facts. - **User Story 4 (Phase 6)**: Starts after User Story 1 and User Story 2 and should finish after User Story 3 if restore-selection RBAC visibility is included in the same pass. - **Polish (Phase 7)**: Starts after the desired user stories are complete. ### User Story Dependencies - **US1**: Depends only on Setup and Foundational work. - **US2**: Depends only on Setup and Foundational work and shares the same resolver contract as US1. - **US3**: Depends on US1 and US2 because step 1 and step 2 reuse the backup-set and item-level quality models introduced there. - **US4**: Depends on US1 and US2 for truth surfaces and should include US3 when restore-wizard visibility checks are part of the same test pass. ### Within Each User Story - Tests should be added or updated before the corresponding behavior change is considered complete. - Shared resolver and resource wiring should land before story-specific copy cleanup for the same surface. - Story-level focused test runs should pass before moving to the next priority slice. ### Parallel Opportunities - `T002` and `T004` can run in parallel once `T001` and `T003` establish the helper signatures and metadata rules. - `T006` and `T007` can run in parallel after `T005` lands the shared wiring points. - `T008` and `T009` can run in parallel for US1. - `T014`, `T015`, and `T016` can run in parallel for US2. - `T022` and `T023` can run in parallel for US3. - `T028` and `T029` can run in parallel for US4. - `T033` and story-specific cleanup reviews can run in parallel once feature behavior is stable. --- ## Parallel Example: User Story 1 ```bash # Story 1 tests in parallel: Task: T008 tests/Feature/Filament/BackupQualityTruthSurfaceTest.php Task: T009 tests/Feature/Filament/BackupSetEnterpriseDetailPageTest.php # Story 1 implementation after assertions are set: Task: T010 app/Filament/Resources/BackupSetResource.php Task: T012 app/Support/BackupQuality/BackupQualityResolver.php ``` ## Parallel Example: User Story 2 ```bash # Story 2 tests in parallel: Task: T014 tests/Feature/Filament/BackupItemsRelationManagerFiltersTest.php Task: T015 tests/Feature/Filament/PolicyVersionQualityTruthSurfaceTest.php Task: T016 tests/Feature/Filament/PolicyVersionRestoreViaWizardTest.php # Story 2 implementation split after the resolver contract is fixed: Task: T017 app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php Task: T018 app/Filament/Resources/PolicyVersionResource.php ``` ## Parallel Example: User Story 3 ```bash # Story 3 tests in parallel: Task: T022 tests/Feature/Filament/RestoreSelectionQualityTruthTest.php Task: T023 tests/Feature/Filament/RestoreItemSelectionTest.php # Story 3 implementation split after the selection copy is agreed: Task: T024 app/Filament/Resources/RestoreRunResource.php Task: T025 app/Filament/Resources/RestoreRunResource.php ``` ## Parallel Example: User Story 4 ```bash # Story 4 tests in parallel: Task: T028 tests/Feature/Rbac/BackupQualityVisibilityTest.php Task: T029 tests/Feature/Rbac/CreateRestoreRunAuthorizationTest.php # Story 4 implementation split after RBAC expectations are locked: Task: T030 app/Filament/Resources/BackupSetResource.php Task: T031 app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php ``` --- ## Implementation Strategy ### MVP First - Complete Phase 1 and Phase 2. - Deliver User Story 1 as the first usable increment so operators can judge backup-set quality early. - Validate that lifecycle truth and backup-quality truth are clearly separated on backup-set list and detail surfaces. ### Incremental Delivery - Add User Story 2 next so item and version strength become explicit everywhere operators inspect backup inputs. - Add User Story 3 after that so restore selection inherits the same quality truth before risk checks. - Add User Story 4 last to verify RBAC-safe truth visibility across read and restore-linked surfaces. ### Verification Finish - Run Pint on touched files. - Run the focused verification pack from `quickstart.md`. - Run the manual quickstart validation pass for backup-set, policy-version, restore-selection, and RBAC outcomes. - Offer the broader test suite only after the focused pack passes.