258 lines
20 KiB
Markdown
258 lines
20 KiB
Markdown
# Tasks: Restore Safety Integrity
|
|
|
|
**Input**: Design documents from `/specs/181-restore-safety-integrity/`
|
|
**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 `tests/Feature/RestoreRunWizardExecuteTest.php`, `tests/Feature/RestoreRiskChecksWizardTest.php`, `tests/Feature/Filament/RestorePreviewTest.php`, `tests/Feature/Filament/RestoreRunUiEnforcementTest.php`, `tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php`, `tests/Feature/RestoreAuditLoggingTest.php`, `tests/Feature/ExecuteRestoreRunJobTest.php`, `tests/Feature/RestorePreviewDiffWizardTest.php`, existing ops-UX constitution and notification guards under `tests/Feature/OpsUx/`, and new restore-safety tests under `tests/Feature/Filament/`, `tests/Feature/Operations/`, and `tests/Unit/Support/RestoreSafety/`.
|
|
**Operations**: This feature reuses existing `RestoreRun` and `OperationRun` execution records. No new run type, lifecycle transition owner, terminal notification flow, or `summary_counts` producer is introduced; work is limited to restore-specific safety truth and canonical-detail continuity for existing `restore.execute` runs.
|
|
**RBAC**: Existing tenant membership, tenant-manage capability gating, capability-registry usage, and `404` vs `403` semantics must remain unchanged across `/admin/t/{tenant}/restore-runs/...` and `/admin/operations/{run}`. Tests must cover both positive and negative access paths.
|
|
**Operator Surfaces**: The restore wizard must show scope, integrity, execution readiness, and one corrective next step before raw preview or check details. The restore detail surface must elevate follow-up truth and next action above raw result lists. The canonical operation detail must keep restore-specific follow-up truth visible or safely linked.
|
|
**Filament UI Action Surfaces**: No new list, bulk, or destructive actions are introduced. Existing rerun, restore, archive, and force-delete actions remain confirmation-gated and server-authorized; the wizard remains the only primary execution surface.
|
|
**Filament UI UX-001**: The create flow remains a Filament wizard with sectioned steps, and the restore detail remains an infolist-based read surface. New safety messaging must be summary-first and diagnostics-second.
|
|
**Badges**: Any new integrity, safety, or result-attention badge states must route through existing centralized restore badge semantics in `app/Support/Badges/Domains/`.
|
|
|
|
**Organization**: Tasks are grouped by user story so each story can be implemented and validated as an independent increment after the shared restore-safety scaffolding is in place.
|
|
|
|
## Phase 1: Setup (Shared Restore-Safety Scaffolding)
|
|
|
|
**Purpose**: Add the narrow shared restore-safety types and test scaffolding used by every story.
|
|
|
|
- [X] T001 Create the shared restore-safety value objects in `app/Support/RestoreSafety/RestoreScopeFingerprint.php`, `app/Support/RestoreSafety/PreviewIntegrityState.php`, `app/Support/RestoreSafety/ChecksIntegrityState.php`, and `app/Support/RestoreSafety/ExecutionReadinessState.php`
|
|
- [X] T002 [P] Create the shared decision-layer types in `app/Support/RestoreSafety/RestoreSafetyAssessment.php`, `app/Support/RestoreSafety/RestoreExecutionSafetySnapshot.php`, and `app/Support/RestoreSafety/RestoreResultAttention.php`
|
|
- [X] T003 Create the central restore-safety resolver with explicit `invalidate_after_mutation` freshness handling and legacy-stale classification in `app/Support/RestoreSafety/RestoreSafetyResolver.php`
|
|
- [X] T004 [P] Add unit test scaffolding for the new restore-safety namespace, including `current` vs `invalidated` vs legacy `stale` classification, in `tests/Unit/Support/RestoreSafety/RestoreScopeFingerprintTest.php`, `tests/Unit/Support/RestoreSafety/RestoreSafetyAssessmentTest.php`, and `tests/Unit/Support/RestoreSafety/RestoreResultAttentionTest.php`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Shared Wiring)
|
|
|
|
**Purpose**: Wire the shared restore-safety contract into existing restore models, badges, and Filament resource seams before story-specific behavior changes.
|
|
|
|
**⚠️ CRITICAL**: No user story work should begin until this phase is complete.
|
|
|
|
- [X] T005 Extend restore-run basis and snapshot helpers in `app/Models/RestoreRun.php`
|
|
- [X] T006 [P] Add centralized integrity and result-attention badge mappings in `app/Support/Badges/Domains/RestorePreviewDecisionBadge.php`, `app/Support/Badges/Domains/RestoreCheckSeverityBadge.php`, and `app/Support/Badges/Domains/RestoreResultStatusBadge.php`
|
|
- [X] T007 Thread shared restore-safety page-model inputs through `app/Filament/Resources/RestoreRunResource.php` and `app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php`
|
|
- [X] T008 [P] Add shared helper and badge regression coverage in `tests/Unit/RestoreRunTest.php`, `tests/Unit/Badges/RestoreUiBadgesTest.php`, and `tests/Unit/Badges/RestoreRunBadgesTest.php`
|
|
|
|
**Checkpoint**: Restore pages can now consume one shared safety contract for wizard, detail, and monitoring surfaces.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Decide Whether Real Execution Is Responsible (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Make the wizard distinguish current decision evidence, technical startability, and actual safety readiness before real execution is offered calmly.
|
|
|
|
**Independent Test**: Open the restore wizard, generate or omit checks and preview, and verify the confirm step clearly separates current safe readiness from mere technical startability and warning-suppressed caution.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T009 [P] [US1] Extend confirm-step execution gating coverage for current evidence, missing evidence, and warning suppression in `tests/Feature/RestoreRunWizardExecuteTest.php`
|
|
- [X] T010 [P] [US1] Add wizard safety-state rendering coverage for `not_generated`, `current`, `risky`, and `ready_with_caution` scenarios in `tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T011 [US1] Compute preview integrity, checks integrity, execution readiness, and safety readiness in `app/Filament/Resources/RestoreRunResource.php`
|
|
- [ ] T012 [US1] Enforce current fingerprint, current evidence, and hard-confirm validation before real execution queues in `app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php`
|
|
- [X] T013 [US1] Render checks integrity state and one corrective next step in `resources/views/filament/forms/components/restore-run-checks.blade.php`
|
|
- [X] T014 [US1] Render preview basis truth, generated-at context, and calmness suppression in `resources/views/filament/forms/components/restore-run-preview.blade.php`
|
|
- [X] T015 [US1] Persist execution-time safety snapshot data for real restore submissions in `app/Models/RestoreRun.php` and `app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php`
|
|
- [X] T016 [US1] Run the focused wizard safety regression pack in `tests/Feature/RestoreRunWizardExecuteTest.php` and `tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php`
|
|
|
|
**Checkpoint**: The wizard now answers whether the current scope is responsibly executable without collapsing warnings or missing evidence into a calm ready state.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Notice Scope Drift Immediately (Priority: P1)
|
|
|
|
**Goal**: Make prior preview and checks visibly invalid when the selected restore scope changes, instead of silently falling back to a neutral state.
|
|
|
|
**Independent Test**: Generate preview and checks, change selected items, scope mode, backup set, or group mapping, and verify the wizard shows explicit invalidation with rerun guidance before calm execution is available again.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T017 [P] [US2] Extend scope-drift invalidation coverage for selected items, scope mode, backup set, and group mapping mutations in `tests/Feature/RestoreRiskChecksWizardTest.php`
|
|
- [ ] T018 [P] [US2] Add basis-persistence and invalidation-reason coverage for prior preview and checks evidence in `tests/Feature/RestoreRunWizardMetadataTest.php`
|
|
- [ ] T019 [P] [US2] Add stale-versus-invalidated start-gate regressions in `tests/Feature/Hardening/RestoreStartGateStaleTest.php` and `tests/Feature/Hardening/RestoreStartGateUnhealthyTest.php`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T020 [US2] Preserve last-known preview and checks basis plus invalidation reasons when scope-affecting inputs change in `app/Filament/Resources/RestoreRunResource.php`
|
|
- [X] T021 [US2] Store comparison-ready scope, preview, and checks basis payloads on draft and persisted restore runs in `app/Models/RestoreRun.php`
|
|
- [X] T022 [US2] Render explicit `stale` and `invalidated` guidance instead of silent fallback in `resources/views/filament/forms/components/restore-run-checks.blade.php` and `resources/views/filament/forms/components/restore-run-preview.blade.php`
|
|
- [ ] T023 [US2] Run the focused scope-drift regression pack in `tests/Feature/RestoreRiskChecksWizardTest.php`, `tests/Feature/RestoreRunWizardMetadataTest.php`, and `tests/Feature/Hardening/RestoreStartGateStaleTest.php`
|
|
|
|
**Checkpoint**: Scope changes now invalidate prior safety work visibly and suppress calm execution messaging until the evidence is regenerated.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Interpret Restore Results Without Overclaiming Recovery (Priority: P2)
|
|
|
|
**Goal**: Make restore detail tell operators what the run meant, whether follow-up remains, and what to do next before showing raw item diagnostics.
|
|
|
|
**Independent Test**: Open completed, partial, failed, and completed-with-follow-up restore runs and verify the first visible detail section communicates result truth, follow-up truth, cause family, and one primary next action without implying tenant recovery.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T024 [P] [US3] Add result-attention coverage for completed, partial, failed, and completed-with-follow-up restore runs in `tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php`
|
|
- [ ] T025 [P] [US3] Extend restore detail rendering assertions for basis truth and non-calm result messaging in `tests/Feature/Filament/RestorePreviewTest.php`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T026 [US3] Build the restore result-attention page model from `results`, assignment outcomes, and execution snapshot data in `app/Filament/Resources/RestoreRunResource.php`
|
|
- [X] T027 [US3] Show preview-basis and checks-basis truth on the detail surface in `resources/views/filament/infolists/entries/restore-preview.blade.php`
|
|
- [X] T028 [US3] Elevate follow-up truth, cause family, and one primary next action above raw item lists in `resources/views/filament/infolists/entries/restore-results.blade.php`
|
|
- [ ] T029 [US3] Preserve non-overclaiming restore wording for completed and partial outcomes in `app/Filament/Resources/RestoreRunResource/Pages/ViewRestoreRun.php` and `app/Support/Badges/Domains/RestoreResultStatusBadge.php`
|
|
- [X] T030 [US3] Run the focused restore detail regression pack in `tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php` and `tests/Feature/Filament/RestorePreviewTest.php`
|
|
|
|
**Checkpoint**: Restore detail now communicates execution outcome and open follow-up work without overstating recovery certainty.
|
|
|
|
---
|
|
|
|
## Phase 6: User Story 4 - Preserve Restore Truth In Canonical Run Monitoring (Priority: P3)
|
|
|
|
**Goal**: Keep restore-specific follow-up truth visible or safely reachable from the canonical operation detail page for restore-linked runs.
|
|
|
|
**Independent Test**: Open restore-linked operation runs from monitoring and restore surfaces and verify restore follow-up truth is visible or reachable within one click, with safe degradation when deeper restore access is unavailable.
|
|
|
|
### Tests for User Story 4
|
|
|
|
- [X] T031 [P] [US4] Add restore-linked canonical detail coverage for visible follow-up truth and safe deep-link behavior in `tests/Feature/Operations/RestoreLinkedOperationDetailTest.php`
|
|
- [ ] T032 [P] [US4] Extend restore execution sync coverage so canonical monitoring preserves restore continuation context in `tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php`
|
|
- [ ] T033 [P] [US4] Extend RBAC-safe degradation coverage for restore-linked operation access and denied restore deep links in `tests/Feature/Filament/RestoreRunUiEnforcementTest.php`
|
|
|
|
### Implementation for User Story 4
|
|
|
|
- [X] T034 [US4] Enrich restore-linked `restore.execute` operation detail payloads with restore continuation truth in `app/Filament/Resources/OperationRunResource.php`
|
|
- [X] T035 [US4] Render safe restore-detail navigation and entitled degradation states on canonical monitoring pages in `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php`
|
|
- [X] T036 [US4] Run the focused canonical continuation regression pack in `tests/Feature/Operations/RestoreLinkedOperationDetailTest.php`, `tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php`, and `tests/Feature/Filament/RestoreRunUiEnforcementTest.php`
|
|
|
|
**Checkpoint**: Canonical operation detail now preserves restore meaning instead of flattening the run to generic telemetry alone.
|
|
|
|
---
|
|
|
|
## Phase 7: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final consistency, formatting, and focused verification across all stories.
|
|
|
|
- [X] T037 [P] Review and align operator-facing restore safety copy in `app/Filament/Resources/RestoreRunResource.php`, `app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php`, `resources/views/filament/forms/components/restore-run-checks.blade.php`, `resources/views/filament/forms/components/restore-run-preview.blade.php`, and `resources/views/filament/infolists/entries/restore-results.blade.php`
|
|
- [X] T038 [P] Run shared helper and badge verification in `tests/Unit/Support/RestoreSafety/RestoreScopeFingerprintTest.php`, `tests/Unit/Support/RestoreSafety/RestoreSafetyAssessmentTest.php`, `tests/Unit/Support/RestoreSafety/RestoreResultAttentionTest.php`, and `tests/Unit/Badges/RestoreUiBadgesTest.php`
|
|
- [X] T039 Run formatting with `vendor/bin/sail bin pint --dirty --format agent` as required by `specs/181-restore-safety-integrity/quickstart.md`
|
|
- [X] T040 Run the final focused verification pack from `specs/181-restore-safety-integrity/quickstart.md` against `tests/Feature/RestoreRunWizardExecuteTest.php`, `tests/Feature/RestoreRiskChecksWizardTest.php`, `tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php`, `tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php`, `tests/Feature/Operations/RestoreLinkedOperationDetailTest.php`, and `tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php`
|
|
- [ ] T041 [P] Extend invalidation audit-derivability coverage in `tests/Feature/RestoreAuditLoggingTest.php` and `tests/Feature/RestoreRunWizardMetadataTest.php`
|
|
- [ ] T042 [P] Extend restore execution and preview-diff non-regression coverage in `tests/Feature/ExecuteRestoreRunJobTest.php` and `tests/Feature/RestorePreviewDiffWizardTest.php`
|
|
- [ ] T043 [P] Run ops-UX constitution and notification guard coverage in `tests/Feature/OpsUx/Constitution/DirectStatusTransitionGuardTest.php`, `tests/Feature/OpsUx/Constitution/JobDbNotificationGuardTest.php`, `tests/Feature/OpsUx/Constitution/LegacyNotificationGuardTest.php`, `tests/Feature/OpsUx/OperationRunSummaryCountsIncrementTest.php`, `tests/Feature/OpsUx/Regression/RestoreRunTerminalNotificationTest.php`, `tests/Feature/OpsUx/NotificationViewRunLinkTest.php`, and `tests/Feature/OpsUx/QueuedToastCopyTest.php`
|
|
- [ ] T044 Run the manual validation pass in `specs/181-restore-safety-integrity/quickstart.md` to verify the 15-second and one-click operator success criteria
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: Starts immediately and establishes the shared restore-safety types.
|
|
- **Foundational (Phase 2)**: Depends on Setup and blocks all story work until restore models, badges, and resource seams consume the shared contract.
|
|
- **User Story 1 (Phase 3)**: Starts after Foundational and delivers the first operator-safe execution decision surface.
|
|
- **User Story 2 (Phase 4)**: Starts after Foundational and should follow User Story 1 closely because it reuses the same wizard safety contract while hardening scope invalidation.
|
|
- **User Story 3 (Phase 5)**: Starts after Foundational and depends on the shared execution-snapshot and result-attention contract introduced in earlier phases.
|
|
- **User Story 4 (Phase 6)**: Starts after User Story 3 because canonical monitoring reuses restore result-attention truth.
|
|
- **Polish (Phase 7)**: Starts after the desired user stories are complete.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1**: Depends only on Setup and Foundational work.
|
|
- **US2**: Depends on Setup and Foundational work and should reuse the wizard safety contract delivered in US1.
|
|
- **US3**: Depends on Setup and Foundational work plus the execution-snapshot plumbing from US1.
|
|
- **US4**: Depends on Setup and Foundational work plus the restore result-attention contract from US3.
|
|
|
|
### Within Each User Story
|
|
|
|
- Tests should be added or updated before the corresponding behavior change is considered complete.
|
|
- Shared resource and model wiring should land before Blade rendering tasks for the same story.
|
|
- Story-level focused test runs should pass before moving to the next priority slice.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T002` and `T004` can run in parallel after the core namespace shape from `T001` is agreed.
|
|
- `T006` and `T008` can run in parallel after `T005` defines the shared restore-run basis helpers.
|
|
- `T009` and `T010` can run in parallel for US1.
|
|
- `T017`, `T018`, and `T019` can run in parallel for US2.
|
|
- `T024` and `T025` can run in parallel for US3.
|
|
- `T031`, `T032`, and `T033` can run in parallel for US4.
|
|
- `T037` and `T038` can run in parallel once feature code is stable.
|
|
- `T041`, `T042`, and `T043` can run in parallel during final verification.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# Story 1 tests in parallel:
|
|
Task: T009 tests/Feature/RestoreRunWizardExecuteTest.php
|
|
Task: T010 tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php
|
|
|
|
# Story 1 implementation split after expectations are locked:
|
|
Task: T011 app/Filament/Resources/RestoreRunResource.php
|
|
Task: T014 resources/views/filament/forms/components/restore-run-preview.blade.php
|
|
```
|
|
|
|
## Parallel Example: User Story 2
|
|
|
|
```bash
|
|
# Story 2 regressions in parallel:
|
|
Task: T017 tests/Feature/RestoreRiskChecksWizardTest.php
|
|
Task: T018 tests/Feature/RestoreRunWizardMetadataTest.php
|
|
Task: T019 tests/Feature/Hardening/RestoreStartGateStaleTest.php
|
|
|
|
# Story 2 implementation split after invalidation rules are fixed:
|
|
Task: T020 app/Filament/Resources/RestoreRunResource.php
|
|
Task: T022 resources/views/filament/forms/components/restore-run-checks.blade.php
|
|
```
|
|
|
|
## Parallel Example: User Story 3
|
|
|
|
```bash
|
|
# Story 3 tests in parallel:
|
|
Task: T024 tests/Feature/Filament/RestoreResultAttentionSurfaceTest.php
|
|
Task: T025 tests/Feature/Filament/RestorePreviewTest.php
|
|
|
|
# Story 3 implementation split after attention-model assertions are clear:
|
|
Task: T026 app/Filament/Resources/RestoreRunResource.php
|
|
Task: T028 resources/views/filament/infolists/entries/restore-results.blade.php
|
|
```
|
|
|
|
## Parallel Example: User Story 4
|
|
|
|
```bash
|
|
# Story 4 tests in parallel:
|
|
Task: T031 tests/Feature/Operations/RestoreLinkedOperationDetailTest.php
|
|
Task: T032 tests/Feature/OpsUx/RestoreExecutionOperationRunSyncTest.php
|
|
Task: T033 tests/Feature/Filament/RestoreRunUiEnforcementTest.php
|
|
|
|
# Story 4 implementation split after restore-continuation expectations are set:
|
|
Task: T034 app/Filament/Resources/OperationRunResource.php
|
|
Task: T035 app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First
|
|
|
|
- Complete Phase 1 and Phase 2.
|
|
- Deliver User Story 1 and User Story 2 as the minimum safe restore-decision slice.
|
|
- Validate that the wizard now distinguishes current evidence, invalidated evidence, and warning-suppressed caution before real execution is offered calmly.
|
|
|
|
### Incremental Delivery
|
|
|
|
- Add User Story 3 next to harden restore detail truth and follow-up guidance.
|
|
- Add User Story 4 last to preserve restore meaning on canonical monitoring without duplicating persistence.
|
|
|
|
### Verification Finish
|
|
|
|
- Run Pint on touched files.
|
|
- Run the focused restore safety pack from `quickstart.md`.
|
|
- Run the manual quickstart validation pass for the 15-second and one-click operator outcomes.
|
|
- Offer the broader suite only after the focused pack passes.
|