From b4cf61d8c744220e4f193c4ecf47c4557c020156 Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Sun, 24 May 2026 23:42:49 +0200 Subject: [PATCH] spec: add Spec 332 restore run preview productization --- .../plan.md | 64 +++++++++++++ .../spec.md | 96 +++++++++++++++++++ .../tasks.md | 23 +++++ 3 files changed, 183 insertions(+) create mode 100644 specs/332-restore-run-preview-productization/plan.md create mode 100644 specs/332-restore-run-preview-productization/spec.md create mode 100644 specs/332-restore-run-preview-productization/tasks.md diff --git a/specs/332-restore-run-preview-productization/plan.md b/specs/332-restore-run-preview-productization/plan.md new file mode 100644 index 00000000..cf45523a --- /dev/null +++ b/specs/332-restore-run-preview-productization/plan.md @@ -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. diff --git a/specs/332-restore-run-preview-productization/spec.md b/specs/332-restore-run-preview-productization/spec.md new file mode 100644 index 00000000..ff79a003 --- /dev/null +++ b/specs/332-restore-run-preview-productization/spec.md @@ -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. diff --git a/specs/332-restore-run-preview-productization/tasks.md b/specs/332-restore-run-preview-productization/tasks.md new file mode 100644 index 00000000..0c415e83 --- /dev/null +++ b/specs/332-restore-run-preview-productization/tasks.md @@ -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`.