spec: add Spec 332 restore run preview productization
This commit is contained in:
Ahmed Darrazi
parent
f967db7983
commit
b4cf61d8c7
64
specs/332-restore-run-preview-productization/plan.md
Normal file
64
specs/332-restore-run-preview-productization/plan.md
Normal file
@ -0,0 +1,64 @@
|
||||
# Implementation Plan: Spec 332 - Restore Run Preview Productization (Wizard Safety Gates)
|
||||
|
||||
- Branch: `332-product-process-flow-system-v1`
|
||||
- Date: 2026-05-24
|
||||
- Spec: `specs/332-restore-run-preview-productization/spec.md`
|
||||
|
||||
## Summary
|
||||
|
||||
Productize the Restore Run wizard preview step so it remains decision-first and truthfully gated:
|
||||
|
||||
- Block navigation to confirmation until checks + preview are current and execution is technically allowed.
|
||||
- Collapse “safety gates” detail by default; show concise guidance first.
|
||||
- Improve preview toast copy so it communicates real meaning (no scope, no changes, changes).
|
||||
|
||||
## Affected Surfaces / Files
|
||||
|
||||
- Wizard logic:
|
||||
- `apps/platform/app/Filament/Resources/RestoreRunResource.php`
|
||||
- Copy:
|
||||
- `apps/platform/app/Support/RestoreSafety/RestoreSafetyCopy.php`
|
||||
- Preview component:
|
||||
- `apps/platform/resources/views/filament/forms/components/restore-run-preview.blade.php`
|
||||
- Tests:
|
||||
- `apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php`
|
||||
- `apps/platform/tests/Browser/Spec332RestoreRunWizardPreviewSmokeTest.php`
|
||||
|
||||
## Technical Approach
|
||||
|
||||
1. **Wizard gate enforcement**
|
||||
- Add `afterValidation` gate on the Preview step.
|
||||
- Evaluate existing restore safety state (`wizardSafetyState`) to check:
|
||||
- preview integrity is current
|
||||
- checks integrity is current
|
||||
- execution readiness is allowed
|
||||
- Block navigation using `Filament\Support\Exceptions\Halt` and a clear Notification message.
|
||||
|
||||
2. **Decision-first preview UI**
|
||||
- Keep safety details collapsed by default, with an explicit “View safety gates” affordance.
|
||||
- Ensure primary preview content remains readable (avoid noisy type/platform copy in the main list).
|
||||
|
||||
3. **Tests**
|
||||
- Feature test: confirmation guidance copy and preview readability.
|
||||
- Browser smoke: run checks + generate preview, then assert gates are collapsed and execution is shown as unavailable.
|
||||
|
||||
## Validation Commands
|
||||
|
||||
Narrow first:
|
||||
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/RestoreRunPreviewProductizationTest.php --compact`
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/RestorePreviewTest.php --compact`
|
||||
- `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/RestoreSafetyIntegrityWizardTest.php --compact`
|
||||
|
||||
Browser smoke:
|
||||
|
||||
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec332RestoreRunWizardPreviewSmokeTest.php --compact`
|
||||
|
||||
Formatting:
|
||||
|
||||
- `cd apps/platform && ./vendor/bin/sail pint --dirty`
|
||||
- `git diff --check`
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Spec 334 (nested Filament/Livewire context hardening) must be present on the branch to avoid tenantless Livewire update crashes during wizard smoke validation.
|
||||
96
specs/332-restore-run-preview-productization/spec.md
Normal file
96
specs/332-restore-run-preview-productization/spec.md
Normal file
@ -0,0 +1,96 @@
|
||||
# Feature Specification: Spec 332 - Restore Run Preview Productization (Wizard Safety Gates)
|
||||
|
||||
- Feature Branch: `332-product-process-flow-system-v1`
|
||||
- Created: 2026-05-24
|
||||
- Status: Draft
|
||||
- Input: parked WIP ("spec-332-restore-productization-blocked-by-livewire-context") + repo implementation + tests
|
||||
|
||||
## Spec Candidate Check *(mandatory — SPEC-GATE-001)*
|
||||
|
||||
- **Problem**: Restore wizard preview and confirmation gates were not productized enough: operators could reach confirmation without current preview/checks, and the preview step exposed too much gate detail by default.
|
||||
- **Today's failure**: Operators can misinterpret wizard progress as readiness. In addition, Livewire update lifecycles previously caused context loss crashes (addressed by Spec 334), blocking stable browser smoke validation for this flow.
|
||||
- **User-visible improvement**: Preview step is decision-first: safe guidance is visible, “safety gates” details are collapsed by default, and progression to confirmation is blocked unless checks + preview are current and execution is technically allowed.
|
||||
- **Smallest enterprise-capable version**: Add wizard step gating + copy improvements + one feature test + one browser smoke test. No tenancy rewrite, no restore domain redesign, no new persisted entities.
|
||||
- **Explicit non-goals**: No new restore risk engine, no new preview diff format, no new global trust framework, no new workflow beyond the existing wizard steps.
|
||||
- **Permanent complexity imported**: Small amount of wizard step logic (`afterValidation` halt), UI copy tweaks, and two tests (Feature + Browser).
|
||||
- **Why now**: Restore is high-risk and operator-critical; readiness must be truthful and stable to proceed with restore flow productization.
|
||||
- **Why not local**: Wizard gating and preview surface are shared operator behavior; leaving it implicit causes repeated operator confusion and regressions.
|
||||
- **Approval class**: Core Enterprise
|
||||
- **Red flags triggered**: UI surface behavior change (wizard). Defense: bounded change with tests + browser smoke.
|
||||
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 1 | **Gesamt: 9/12**
|
||||
- **Decision**: approve
|
||||
|
||||
## Spec Scope Fields *(mandatory)*
|
||||
|
||||
- **Scope**: tenant (environment-bound restore wizard)
|
||||
- **Primary Routes**:
|
||||
- `/admin/workspaces/{workspace}/environments/{environment}/restore-runs/create`
|
||||
- **Data Ownership**:
|
||||
- Uses existing `RestoreRun` draft state; no new tables.
|
||||
- Preview/check data remains wizard/restore-run owned, derived by existing resolvers.
|
||||
- **RBAC**:
|
||||
- Tenant membership required.
|
||||
- Existing restore capabilities remain the authority; this spec does not change policy rules.
|
||||
|
||||
## UI Surface Impact *(mandatory — UI-COV-001)*
|
||||
|
||||
- [ ] No UI surface impact
|
||||
- [x] Existing page changed
|
||||
- [ ] New page/route added
|
||||
- [ ] Navigation changed
|
||||
- [ ] Filament panel/provider surface changed
|
||||
- [x] New modal/drawer/wizard/action added
|
||||
- [x] New table/form/state added
|
||||
- [ ] Customer-facing surface changed
|
||||
- [x] Dangerous action changed
|
||||
- [x] Status/evidence/review presentation changed
|
||||
- [ ] Workspace/environment context presentation changed
|
||||
|
||||
## UI/Productization Coverage *(mandatory)*
|
||||
|
||||
- **Route/page/surface**: Restore Run create wizard preview + confirmation gates.
|
||||
- **Design depth**: Manual Review Required (operator-critical, risky workflow).
|
||||
- **Repo-truth level**: repo-verified (feature + browser tests).
|
||||
- **New pattern required**: none; reuse existing RestoreSafety resolver state, improve decision-first copy + gating.
|
||||
- **Screenshot required**: no (covered by dedicated browser smoke test assertions).
|
||||
- **Dangerous-action review required**: yes; “execute restore” remains gated and this spec tightens readiness gating.
|
||||
- **Coverage files updated or explicitly not needed**: `N/A - no UI audit registry update in this change set; scope is covered via browser smoke + feature tests`.
|
||||
|
||||
## Goals
|
||||
|
||||
1. Block wizard progression to confirmation unless:
|
||||
- safety checks are current for the selected scope
|
||||
- preview is current for the selected scope
|
||||
- execution is technically allowed (no technical blockers)
|
||||
2. Improve preview-step decision-first messaging:
|
||||
- guidance for “review and confirm” when preview + checks are complete
|
||||
- safety gate details collapsed by default (operator can expand)
|
||||
3. Keep the restore preview surface readable:
|
||||
- avoid noisy type/platform strings in the primary preview list presentation
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No changes to restore execution behavior, queue orchestration, or Graph contract paths.
|
||||
- No new “trust framework” outside restore wizard surfaces.
|
||||
- No new persisted state families or tables.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
- Gating is enforced in the wizard using Filament’s step lifecycle (`afterValidation`) and `Halt` to prevent navigation.
|
||||
- Notifications are used to explain why progression is blocked (checks required, preview required, technical blocker).
|
||||
- Preview notification copy is adjusted to be user-meaningful (“No policy changes detected” vs raw counts).
|
||||
|
||||
## Testing / Lane / Runtime Impact
|
||||
|
||||
- **Test purpose / classification**: Feature + Browser smoke
|
||||
- **Validation lanes**: confidence + browser
|
||||
- **New tests**:
|
||||
- `apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php`
|
||||
- `apps/platform/tests/Browser/Spec332RestoreRunWizardPreviewSmokeTest.php`
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Wizard cannot proceed from Preview → Confirmation when checks are missing/stale, preview is missing/stale, or execution is technically blocked.
|
||||
- Preview step shows “View safety gates” by default (collapsed), and does not default-open the full gates panel.
|
||||
- Confirmation guidance text is visible when preview + checks are complete.
|
||||
- Feature test and browser smoke test pass.
|
||||
23
specs/332-restore-run-preview-productization/tasks.md
Normal file
23
specs/332-restore-run-preview-productization/tasks.md
Normal file
@ -0,0 +1,23 @@
|
||||
# Tasks: Spec 332 - Restore Run Preview Productization (Wizard Safety Gates)
|
||||
|
||||
**Input**: `specs/332-restore-run-preview-productization/spec.md`, `specs/332-restore-run-preview-productization/plan.md`
|
||||
|
||||
## Phase 1: Restore parked WIP
|
||||
|
||||
- [x] Base work on updated `platform-dev` (done by branching from `platform-dev`).
|
||||
- [x] Restore parked 332 WIP changes (applied from stash).
|
||||
|
||||
## Phase 2: Implement wizard gating + preview productization
|
||||
|
||||
- [x] Add Preview-step `afterValidation` gate to block navigation when checks/preview are not current or execution is technically blocked.
|
||||
- [x] Improve preview generated toast copy (no scope / no changes / changes).
|
||||
- [x] Ensure preview surface stays decision-first and safety gates are collapsed by default.
|
||||
- [x] Add next-action copy for `review_and_confirm`.
|
||||
|
||||
## Phase 3: Tests + formatting
|
||||
|
||||
- [x] Add feature regression test: `apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php`.
|
||||
- [x] Add browser smoke: `apps/platform/tests/Browser/Spec332RestoreRunWizardPreviewSmokeTest.php`.
|
||||
- [x] Run targeted restore tests.
|
||||
- [x] Run browser smoke test.
|
||||
- [x] Run `pint` and `git diff --check`.
|
||||
Loading…
Reference in New Issue
Block a user