# Implementation Plan: Restore Run Wizard (011)

**Branch**: `feat/011-restore-run-wizard` | **Date**: 2025-12-30  
**Input**: Feature specification in `specs/011-restore-run-wizard/spec.md`

## Summary
Refactor Restore Run creation into a **Filament Wizard** that enforces **Safety First**:
source → scope → safety checks → preview → confirm + execute.

Leverage existing restore primitives (`RestoreService::preview()` / `RestoreService::execute()`) and incrementally introduce:
- structured **risk checks**
- **diff preview** artifacts/summaries
- stronger **execution gating** + audit fields

## Technical Context (current code)
- Filament Resource: `app/Filament/Resources/RestoreRunResource.php` (single form today)
- Restore engine: `app/Services/Intune/RestoreService.php` (preview + execute)
- Diff tools: `app/Services/Intune/PolicyNormalizer.php` + `app/Services/Intune/VersionDiff.php`
- Data model: `restore_runs` already stores `preview`, `results`, `metadata`, `requested_items`

## Phase 1 — Data + State Model (Wizard-ready)
- Define restore run lifecycle statuses (string enum values).
- Decide what is stored as dedicated columns vs `restore_runs.metadata` JSON.
- Add minimal persistence for wizard state:
  - `scope_mode`, `check_summary`, `check_results`, `preview_summary`, `confirmed_at/by`, `environment`, `highlander_label`.

**Checkpoint**: RestoreRun can represent wizard progression and persist computations.

## Phase 2 — Filament Wizard UI (Create Restore Run)
- Replace the single Create form with a 5-step wizard UI.
- Implement step-level validation and state resets (changing backup set resets downstream).
- Keep dry-run default ON, and make execution UI unavailable until the wizard rules are satisfied.

**Checkpoint**: Wizard is usable end-to-end in dry-run.

## Phase 3 — Restore Scope Builder (Selection UX)
- Build grouped selection UI for BackupItems (type/platform), with search and “select all”.
- Clearly mark:
  - foundations vs policies
  - preview-only types
  - items missing policy_version linkage / snapshot completeness hints (optional)

**Checkpoint**: Scoping is explicit, scalable, and safe.

## Phase 4 — Safety & Conflict Checks (RestoreRiskChecker)
- Implement server-side checks for the chosen scope.
- Persist results on the RestoreRun and display with severity badges.
- Block execution if blockers exist.

**Checkpoint**: Defensive layer in place; blockers stop execution.

## Phase 5 — Preview (RestoreDiffGenerator)
- Generate a diff summary (minimum) comparing backup snapshot vs current target state.
- Persist preview summary (and optionally per-item diffs with limits).
- Require preview completion before allowing execute.

**Checkpoint**: Preview step is a hard gate for execute and is auditable.

## Phase 6 — Confirm & Execute
- Add explicit confirmations:
  - “I reviewed the impact”
  - tenant hard-confirm (Highlander)
  - environment badge (frozen at run creation)
- Execute restore via queue job (preferred) or synchronous execution (only if queue is out of scope for MVP).
- Update run statuses and persist outcomes.

**Checkpoint**: Execution is safe, gated, and traceable.

## Phase 7 — Tests + QA
- Pest feature tests for:
  - wizard gating rules (execute disabled until conditions satisfied)
  - safety checks persistence and blocking behavior
  - preview summary generation
- Run targeted tests and Pint.