TenantAtlas/specs/332-restore-run-preview-productization/spec.md

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