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
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• 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.