TenantAtlas/specs/333-restore-create-ux-final-productization/spec.md

Feature Specification: Spec 333 - Restore Create UX Final Productization

• Feature Branch: 333-restore-create-ux-final-productization
• Created: 2026-05-26
• Status: Draft
• Type: Runtime UX productization / Restore Create wizard refinement / no new architecture
• Runtime posture: Narrow UI/UX productization on top of Spec 332. No backend rewrite. No new flow system.
• Input: User-provided Spec 333 draft, explicitly depending on Spec 332 Product Process Flow System v1.

Dependency Context

Spec 333 builds on the completed Spec 332 foundation:

• RestoreRunCreatePresenter is the centralized Restore Create product-state contract.
• Product Process Flow component/pattern already exists.
• Step 1 full Restore Safety Gates already exists.
• Step 2+ compact Restore Safety Status already exists.
• Restore Proof panel already exists.
• Mapping resolver, group picker, validation, preview, and confirm foundations already exist.

Spec 333 must not rebuild these foundations. It productizes the visible Restore Create wizard experience over the existing contract and components.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Restore Create now has the Spec 332 safety/proof foundation, but the visible wizard still needs final productization across all five steps so operators can decide whether it is safe to continue without reading raw fields, IDs, diagnostics, or internal validation details.
• Today's failure: Operators can still encounter raw technical form sprawl, repeated helper text, item-flood preview, ambiguous next-gate copy, provider/startability wording, or proof language that could imply more certainty than the pre-execution state supports.
• User-visible improvement: Every Restore Create step presents status, reason, impact, proof basis, blockers, and one primary next action using calm enterprise workflow hierarchy.
• Smallest enterprise-capable version: Polish the existing Restore Create wizard, Blade components, presenter output usage, mapping resolver, group picker, validation, preview, confirmation, tests, and screenshots. Reuse Spec 332 state truth. No new persisted truth, backend behavior, migrations, packages, or architecture.
• Explicit non-goals: No new Product Process Flow architecture, no new presenter, no backend rewrite, no OperationRun model changes, no ProviderGateway behavior changes, no Graph calls, no migrations, no packages, no Restore Run Detail productization, no post-execution result page productization, and no migration of unrelated surfaces into Product Process Flow.
• Permanent complexity imported: Focused product copy, view layout refinements, deterministic presenter assertions, feature/browser coverage, and Spec 333 screenshots. No new source of truth or framework.
• Why now: Restore is a high-risk operator workflow. Spec 332 made the state contract available; the next safe step is to remove final visible UX ambiguity before expanding restore proof/result work.
• Why not local: The implementation stays local to Restore Create rendering, but it must use the existing centralized presenter contract so Blade fragments do not recreate independent gate/proof/next-action truth.
• Approval class: Core Enterprise
• Red flags triggered: High-risk restore workflow, dangerous action presentation, status/proof messaging. Defense: bounded UI productization, explicit proof boundaries, no backend rewrite, targeted tests, browser screenshots.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitat: 2 | Produktnahe: 2 | Wiederverwendung: 1 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: tenant / environment-bound Restore Create wizard
• Primary Routes:
  • /admin/workspaces/{workspace}/environments/{environment}/restore-runs/create
• Data Ownership:
  • Existing tenant-owned RestoreRun draft state only.
  • Existing BackupSet, BackupItem, EntraGroup, provider connection, validation, preview, and restore safety derived state only.
  • No new table, migration, persisted state, queue, scheduler, storage, or env var.
• RBAC:
  • Existing workspace membership and managed-environment capability checks remain authoritative.
  • Existing Create Restore Run access remains capability-gated.
  • Execution availability remains controlled by existing restore readiness, confirmation, and capability behavior.

UI Surface Impact (mandatory - UI-COV-001)

Does this spec add, remove, rename, or materially change any reachable UI surface?

• 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, including Select Backup Set, Define Restore Scope, Validate, Preview, and Confirm & Execute.
• Current or new page archetype: Environment-bound dangerous workflow wizard.
• Design depth: Strategic Surface / Manual Review Required because restore is operator-critical and high-risk.
• Repo-truth level: repo-verified foundation via Spec 332, existing Restore Create code, and browser screenshots.
• Existing pattern reused: Spec 332 Product Process Flow, RestoreRunCreatePresenter, restore safety/proof panels, Spec 325 restore safety target image direction, UI-014 restore runs page report.
• New pattern required: none.
• Screenshot required: yes, save to specs/333-restore-create-ux-final-productization/artifacts/screenshots/.
• Page audit required: no new page audit required unless implementation discovers route/archetype drift; existing Restore Runs audit remains the coverage anchor.
• Customer-safe review required: yes for proof and recovery claims; no customer-facing surface is added.
• Dangerous-action review required: yes; confirmation/execution copy must not overclaim recovery, operation proof, post-run evidence, health, or customer safety.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - existing route/archetype coverage remains valid; Spec 333 package screenshots provide focused proof unless implementation discovers coverage drift
• No-impact rationale when applicable: N/A - reachable UI is materially changed.

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, wizard next actions, proof panels, diagnostics disclosure, action links, dangerous confirmation, browser screenshots.
• Systems touched: Restore Create wizard, Product Process Flow, Restore Proof, restore safety copy, mapping resolver, group picker, validation summary, preview summary, confirm panel.
• Existing pattern(s) to extend: Spec 332 Product Process Flow and Restore Create Presenter contract.
• Shared contract / presenter / builder / renderer to reuse:
  • apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php
  • apps/platform/resources/views/filament/forms/components/restore-run-safety-gates.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-proof-aside.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-*
  • BadgeRenderer / BadgeDomain where badge semantics already exist
  • OperationRunLinks for operation navigation where already supported
• Why the existing shared path is sufficient or insufficient: sufficient; Spec 332 created the shared flow/presenter foundation and this spec only tightens display, copy, grouping, tests, and screenshot proof.
• Allowed deviation and why: none planned. If a view needs local layout polish, it must still render presenter contract state and not calculate independent truth.
• Consistency impact: status, reason, impact, next action, gate state, proof, diagnostics, navigation labels, and copy guardrails must stay aligned across all five steps.
• Review focus: prevent parallel gate/proof truth in Blade, prevent raw technical defaults, and verify no overclaiming before execution/post-run evidence.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes, presentation only for pre-execution proof, execution readiness, and navigation links.
• Shared OperationRun UX contract/layer reused: existing restore execution flow, OperationRunLinks, and existing OperationRun presentation paths only.
• Delegated start/completion UX behaviors: existing create/execute behavior remains unchanged. Spec 333 may clarify visible readiness and pre-execution proof copy only.
• Local surface-owned behavior that remains: restore initiation inputs, preview/dry-run toggle, typed confirmation, and wizard decision display.
• Queued DB-notification policy: N/A - no new notification policy.
• Terminal notification path: N/A - no terminal notification change.
• Exception required?: none.

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes, display-only provider readiness and directory group mapping copy.
• Boundary classification: mixed, but display changes must preserve existing provider-owned seams.
• Seams affected: provider connection readiness copy, directory group cache/group picker copy, target mapping labels, provider connection navigation.
• Neutral platform terms preserved or introduced: environment, provider connection, target mapping, operation proof, post-run evidence, restore scope.
• Provider-specific semantics retained and why: directory groups and object IDs remain provider-bound because the existing mapping workflow is Entra group based.
• Why this does not deepen provider coupling accidentally: no Graph calls, no new contracts, no provider registry changes, and provider-specific language is limited to the existing group/provider boundary.
• Follow-up path: none for Spec 333; broader provider readiness productization belongs to a later spec.

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Restore Create wizard	yes	Mixed Filament wizard plus existing custom Blade components	Product Process Flow, proof, status messaging, dangerous confirmation	page, wizard step, presenter contract, modal	no	High-risk productization surface
Group picker modal	yes	Filament modal plus Livewire table	mapping resolver, navigation links	modal, Livewire table, environment context	no	Context and empty-state polish only
Restore preview step	yes	Existing custom Blade component	preview summary, proof, diagnostics	wizard step, presenter preview summary	no	Summary-first layout, no backend change
Confirm & Execute step	yes	Existing Filament fields plus custom panel	dangerous action / confirmation	wizard step, readiness and proof copy	no	High-friction proof-safe presentation

Decision-First Surface Role (mandatory)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Restore Create wizard	Primary Decision Surface	Operator decides whether each restore gate can move forward	status, reason, impact, primary next action, gate status, proof basis	diagnostics, raw IDs, raw diffs, item detail	Primary because restore can change provider configuration	follows source -> scope -> validation -> preview -> confirmation	avoids raw form interpretation
Restore Proof panel	Secondary Evidence / Proof	Operator checks what proof exists for the draft	source backup, target environment, requester, scope, operation proof, post-run evidence	diagnostics	Secondary because it supports the decision card	follows wizard step context	proof is visible without dominating
Mapping resolver	Primary Decision Surface for Step 2	Operator resolves dependencies before validation	resolved/unresolved/skipped counts, source group name, target group name/state	source/target IDs, manual fallback	Primary inside Step 2 only	prevents validation without dependency decision	hides rows until explicit action
Preview detail	Secondary Context	Operator reviews what would change	decision summary, needs attention, change counts, next gate	item detail, raw diff JSON	Secondary to preview decision summary	preview precedes confirmation	avoids item-card flood

Audience-Aware Disclosure (mandatory)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Restore Create wizard	operator-MSP, support-platform	status, reason, impact, next action, proof basis	validation groups, mapping rows, preview detail	raw IDs, raw diff JSON, provider payloads	state-specific next action	diagnostics and raw payloads	presenter contract owns truth once
Group picker	operator-MSP	source group context and current environment cache state	cache staleness and operation links	object IDs as secondary metadata	choose cached target or enter manual object ID	raw IDs are secondary	source/target names are primary
Confirm step	operator-MSP	confirmation decision summary and proof-safe warnings	readiness details	post-run evidence unavailable before execution	satisfy confirmation or keep preview-only	execution proof claims	proof copy explicitly says unavailable

UI/UX Surface Classification (mandatory)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Restore Create wizard	Workflow / Wizard / Dangerous Action	Environment-bound restore workflow	continue to the next safe gate	wizard step progression	N/A	proof/diagnostics panels and modals	Confirm & Execute step with high friction	Restore Runs list	Restore Run detail after creation	workspace + environment route context	Restore Run	safety state, proof basis, blockers, next action	none
Mapping resolver	Form / Modal / Dependency Resolution	Wizard subflow	resolve mappings	explicit resolver expansion and picker modal	table row selection in picker only	group sync links secondary/open new tab	skip assignment if supported and explicit	N/A	N/A	current environment cache	Mapping	resolved/unresolved/skipped and required state	none

Operator Surface Contract (mandatory)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Restore Create wizard	Tenant operator / MSP operator	Decide whether restore can safely advance	Dangerous workflow wizard	Can this restore safely move forward, what blocks it, what proof exists, what next?	status, reason, impact, gate, proof, one next action	raw IDs, raw diffs, provider errors, raw payloads	source usability, dependency resolution, validation, preview, confirmation, execution/evidence	Preview-only simulation or provider restore execution depending on confirmation	select backup, define scope, resolve mappings, run checks, generate preview, confirm	real restore execution

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no, except Spec Kit screenshots/artifacts
• New abstraction?: no
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: final Restore Create UX clarity and proof-safe decision support.
• Existing structure is insufficient because: Spec 332 provides the contract/foundation, but visible step polish still needs explicit acceptance criteria and tests.
• Narrowest correct implementation: display-only productization on existing presenter/components.
• Ownership cost: focused tests and screenshots for a high-risk wizard.
• Alternative intentionally rejected: new flow system, new presenter, backend rewrite, new state taxonomy, or new persisted proof model.
• Release truth: current-release runtime UX productization.

Compatibility posture

This feature assumes a pre-production environment. No backward compatibility shim, legacy alias, migration support, or historical-data compatibility path is in scope.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature/Livewire, Unit, Browser.
• Validation lane(s): confidence + browser; formatting with Pint; whitespace guard with git diff --check.
• Why this classification and these lanes are sufficient: Restore Create is a high-risk Livewire/Filament wizard with presenter-driven state and browser-visible behavior. Unit tests prove presenter determinism; Feature/Livewire tests prove contract rendering and gating; Browser tests prove the visible workflow/screenshots.
• New or expanded test families: Spec 333 focused Feature/Browser tests and presenter determinism additions.
• Fixture / helper cost impact: use existing restore/backup/environment factories and browser helpers; avoid new broad fixture defaults.
• Heavy-family visibility / justification: browser coverage is explicit and named because the wizard is a critical multi-step UI.
• Special surface test profile: shared-detail-family / dangerous-workflow wizard / browser-smoke.
• Reviewer handoff: reviewers must confirm lane fit, no hidden heavy-governance spread, no new backend behavior, and no false proof claims.
• Budget / baseline / trend impact: expected bounded browser/feature additions only; no structural lane shift.
• Escalation needed: document-in-feature.
• Active feature PR close-out entry: Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec333RestoreCreateUxFinalProductizationTest.php tests/Feature/RestoreGroupMappingTest.php tests/Feature/Filament/RestoreWizardGraphSafetyTest.php tests/Feature/Filament/RestoreRunPreviewProductizationTest.php tests/Unit/Filament/RestoreRunCreatePresenterDeterminismTest.php --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec332 --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec332* --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

User Scenarios & Testing (mandatory)

User Story 1 - Judge source usability from Step 1 (Priority: P1)

As a restore operator, I want Step 1 to show whether a selected backup source is usable, why, what the impact is, what proof exists, and what I should do next.

Why this priority: Restore cannot safely proceed without a usable source. Step 1 is the first opportunity to prevent unsafe assumptions.

Independent Test: Render Step 1 with no backup, unusable backup, degraded usable backup, and clean usable backup; assert decision card, backup quality summary, full safety gates, Restore Proof, diagnostics collapsed, and no false recovery proof.

Acceptance Scenarios:

1. Given no backup set is selected, When Step 1 renders, Then it shows Source required, reason, impact, and primary next action Select backup set.
2. Given a selected backup has no captured/restorable items, When Step 1 renders, Then it shows Source not usable and directs the operator to select another backup.
3. Given a selected usable backup has degraded or mapping issues, When Step 1 renders, Then it shows review-required source state and does not imply execution safety.
4. Given a selected usable clean backup, When Step 1 renders, Then it shows source selected and continues to scope without claiming recovery is verified.

---

User Story 2 - Define scope and resolve mappings without raw form sprawl (Priority: P1)

As a restore operator, I want Step 2 to show a calm scope summary and dependency mapping summary by default, then expand only when I explicitly choose to resolve mappings.

Why this priority: Dependency mapping must be resolved before validation can be trusted, but the default UI should not expose 20+ raw fields or raw GUIDs first.

Independent Test: Render Step 2 default and expanded resolver states with cached target groups, manual fallback, skipped mapping, and empty current-environment cache.

Acceptance Scenarios:

1. Given unresolved mappings exist, When Step 2 renders by default, Then mapping details are hidden, summary counts are visible, compact safety status is visible, proof is visible, full gates are hidden, and Resolve mappings is available.
2. Given the operator opens resolver mode, When mapping rows render, Then source group display name is primary, source ID is secondary, target group display name is primary when cached, target ID is secondary, and manual fallback/skipped states are explicit.
3. Given the current environment has no cached groups, When the group picker opens, Then the empty state references current environment cache, shows context-safe CTAs, and manual fallback remains discoverable if supported.

---

User Story 3 - Validate with product-safe blocker and provider readiness states (Priority: P1)

As a restore operator, I want validation to group blockers, warnings, and safe checks with product-safe copy so provider credential problems or validation blockers do not crash or overclaim success.

Why this priority: Validation gates preview and execution. Provider readiness and blocker messaging must be safe and understandable.

Independent Test: Render no-checks, provider credential missing, blocker, warning, and clean validation states; assert copy, grouped checks, next action, and no internal technical wording.

Acceptance Scenarios:

1. Given no checks have run, When Step 3 renders, Then it shows Validation required and primary next action Run safety checks.
2. Given provider credentials are missing, When Step 3 renders or checks are requested, Then the wizard shows Validation blocked with provider-safe copy and does not 500.
3. Given checks finish with blockers, When the result appears, Then the UI and toast say blockers remain and do not show Safety checks completed.

---

User Story 4 - Review preview summary before item detail (Priority: P1)

As a restore operator, I want Preview to answer what will change before showing item details, so I can review needs attention, changes, unchanged items, blockers, warnings, and the next gate without item-card flooding.

Why this priority: Preview is the decision basis for confirmation; it must be summary-first and gate-consistent.

Independent Test: Generate preview with changed, unchanged, needs-attention, blocker, warning, and current/uncurrent validation states; assert summary-first order and state consistency.

Acceptance Scenarios:

1. Given preview is current and validation is complete, When Step 4 renders, Then it shows Preview complete, Validation complete, Next gate confirmation required, and no stale validation-blocker copy.
2. Given validation is incomplete, When Step 4 renders, Then preview is unavailable and Next gate is validation required.
3. Given many unchanged items exist, When Step 4 renders, Then unchanged items are collapsed or compact and raw diff details are secondary.

---

User Story 5 - Confirm execution with high friction and proof-safe copy (Priority: P1)

As a restore operator, I want Confirm & Execute to show exactly what is being approved and what proof does not exist yet before real execution can be queued.

Why this priority: Execution is the dangerous step. The UI must not imply recovery, operation proof, or post-run evidence before execution and proof exist.

Independent Test: Render confirm states before and after required gates are complete; assert high-friction acknowledgement, typed confirmation where supported, execution availability, dry-run state, and proof-safe copy.

Acceptance Scenarios:

1. Given required gates are incomplete, When Confirm renders, Then execution is unavailable and the operator sees what remains blocked.
2. Given mappings, validation, preview, confirmation, and capability requirements are satisfied, When Confirm renders, Then execution can be queued only after high-friction acknowledgement.
3. Given execution has not run, When Confirm renders, Then operation proof and post-run evidence are unavailable and recovery is not verified.

Functional Requirements

• FR-001: Step 1 MUST render Restore Safety decision card, backup selector, backup quality summary, full Restore Safety Gates, Restore Proof panel, and collapsed diagnostics.
• FR-002: Step 1 MUST represent no backup selected as Source required with reason, impact, and primary next action to select a backup set.
• FR-003: Step 1 MUST represent selected backup with no captured/restorable items as Source not usable and direct the operator to select another backup set.
• FR-004: Step 1 MUST represent usable degraded source state as review required and avoid execution-safety or recovery-proof claims.
• FR-005: Backup quality summary MUST show items captured, metadata-only items, degraded items, assignment/mapping issues, orphaned assignments, and the input-quality caveat.
• FR-006: Step 2 default MUST show define-scope card, scope options, scope impact summary, mapping summary, resolve mappings action, compact Restore Safety Status, Restore Proof, and collapsed diagnostics.
• FR-007: Step 2 default MUST NOT show full mapping details, 20+ raw mapping fields, full seven-gate flow, repeated GUID helper text, or raw IDs as primary labels.
• FR-008: Step 2 scope summary MUST show all items, selected items only, scope impact, and next safety gate; if item-level selection is not supported at runtime, the UI MUST say it explicitly.
• FR-009: Mapping summary MUST show resolved, unresolved, skipped, manual fallback count when used, and whether mapping is required before validation can run.
• FR-010: Mapping resolver expanded mode MUST show Resolve target mappings, progress summary, rows, and exactly one collapse action.
• FR-011: Mapping rows MUST show source group display name first, source ID as secondary metadata, cached target display name first, target ID as secondary metadata, manual fallback badge when manually entered, and skipped state when intentionally skipped.
• FR-012: Mapping rows MUST NOT use raw GUIDs, state labels, or Unresolved (...id) as primary source labels.
• FR-013: Skip assignment behavior MUST be explicit when supported or explicitly unavailable when not supported; SKIP MUST NOT be primary UX.
• FR-014: Group picker MUST show source context, only current-environment cached groups, current-environment empty state, context-safe CTAs, no hardcoded workspace IDs, no 404 links, and manual fallback if supported.
• FR-015: Step 3 MUST show validation summary, grouped blockers/warnings/safe checks, compact Restore Safety Status, Restore Proof, and collapsed diagnostics.
• FR-016: Step 3 MUST show provider credential missing as product-safe validation blocked state, not a raw exception or 500.
• FR-017: Step 3 toast/alert copy MUST NOT show Safety checks completed when blockers exist.
• FR-018: Step 3 default UI MUST NOT show Graph works again, technical startability, write-gate, hard-blocker, raw provider credential exception, raw Graph exception, or platform-context misuse of tenant.
• FR-019: Step 4 Preview MUST be summary-first with decision summary, needs attention, change summary, compact/collapsed unchanged items, compact Restore Safety Status, Restore Proof, and collapsed diagnostics.
• FR-020: Step 4 MUST NOT render every restore item as a large card, raw diff JSON, raw provider payload, or repeated Policy change preview label by default.
• FR-021: Step 4 MUST group preview content into Needs attention, Changes detected, No changes detected, and All reviewed items, with raw details behind disclosure.
• FR-022: Step 4 MUST keep next-gate copy consistent with actual validation/preview state.
• FR-023: Step 5 MUST show confirmation decision summary, preview summary, execution readiness, high-friction acknowledgement, dry-run/preview-only state if supported, typed confirmation/impact acknowledgement if supported, compact Restore Safety Status, Restore Proof, and collapsed diagnostics.
• FR-024: Step 5 MUST show pre-execution proof-safe copy: operation proof unavailable before execution, post-run evidence unavailable before execution, and recovery not verified until post-run evidence exists.
• FR-025: Step 5 MUST NOT claim recovery verified, execution proof complete, post-run evidence available, customer-safe, healthy, or fully restored before actual execution and proof exist.
• FR-026: Execution availability MUST remain gated by required mappings resolved or explicitly allowed skipped, validation not blocked, preview current, confirmation satisfied, and existing RBAC/capability permission.
• FR-027: Restore Proof MUST remain proof basis, not the process flow, and MUST use allowed states only.
• FR-028: Step 1 MUST show full Restore Safety Gates; Step 2+ MUST show compact Restore Safety Status by default with full gates only after explicit View safety gates.
• FR-029: Actions leaving the wizard MUST preserve active workspace/environment context, open secondary flows in a new tab when appropriate, and use task-specific labels.
• FR-030: RestoreRunCreatePresenter MUST remain the single source of truth for gate/proof/next-action state; Blade components MUST render contract state only.
• FR-031: Presenter behavior MUST remain deterministic with no static process-level memoization or fixture state leaks.

Non-Functional Requirements

• NFR-001: The UI MUST remain calm, enterprise-focused, scan-first, and low-noise.
• NFR-002: Diagnostics, raw payloads, raw IDs, and raw diffs MUST be secondary or collapsed by default.
• NFR-003: Long lists MUST render as tables, compact lists, or collapsed disclosures, not large repeated cards.
• NFR-004: Copy MUST be provider-safe and avoid false recovery, health, compliance, or customer-safe claims.
• NFR-005: No new application dependencies, assets, migrations, queues, scheduler changes, storage changes, or environment variables may be introduced.

Data / Truth Source Requirements

• DTR-001: Restore Create product state truth remains derived from existing RestoreRun draft data, restore safety resolver state, preview/check integrity, backup quality, provider readiness, mapping progress, and existing route-bound environment context.
• DTR-002: Pre-execution operation proof and post-run evidence MUST be represented as unavailable unless existing repo behavior proves otherwise after execution.
• DTR-003: Mapping identity MUST prefer cached display names and use object IDs only as secondary metadata or manual fallback input.

Out of Scope

• New Product Process Flow architecture.
• New Restore Create presenter or replacement presenter.
• Backend rewrite.
• OperationRun model changes.
• ProviderGateway behavior changes.
• New Graph calls.
• Migrations or model changes.
• New packages or assets.
• Scheduler, queue, storage, or env var changes.
• Restore Run Detail productization.
• Post-execution Restore Result page productization.
• Baseline Compare, Evidence path, Customer Review, or unrelated surface migration to Product Process Flow.

Edge Cases

• No backup set selected.
• Selected backup has zero captured items.
• Selected backup contains only metadata-only items.
• Selected backup is usable but degraded.
• Unresolved required mappings block validation.
• Skipped mappings are supported or explicitly unavailable.
• Manual target object ID entered without cache match.
• Current environment has no cached directory groups.
• Provider credentials are missing.
• Validation finishes with blockers and warnings.
• Preview is stale, missing, blocked, current, or generated with many unchanged items.
• Confirmation is attempted before gates complete.
• Actor lacks required capability.

Assumptions

• Spec 332 code and tests are the foundation to preserve.
• Restore Create item-level selection is repo-supported today; if implementation discovers a limited state, UI copy must say so rather than inventing support.
• Skip assignment is repo-supported through existing mapping behavior; implementation must keep it explicit or document a tested unsupported branch if current behavior differs.
• RestoreRunResource remains the relevant Filament resource and the Admin panel remains registered through existing Laravel 12 provider registration.
• Browser screenshots may reuse existing Spec 332 fixture patterns but must save under the Spec 333 artifact path.

Risks

• Presenter drift: Blade components could recreate gate/proof truth. Mitigation: tests assert presenter contract usage and determinism.
• Overclaiming proof: Copy could imply execution or recovery proof before execution. Mitigation: forbidden-copy tests and proof-state assertions.
• Browser fixture cost: Nine screenshots can become heavy. Mitigation: explicit browser lane, shared setup, targeted states only.
• Scope creep: Restore Run Detail or post-execution result productization could leak in. Mitigation: hard non-goals and tasks stop at Restore Create.

Open Questions

• None blocking preparation. If implementation discovers a repo-truth mismatch in skip support, item-level selection, or proof-link availability, update this spec/plan before changing runtime behavior.

Acceptance Criteria

Product

• Restore Create Wizard feels like one coherent safety workflow.
• Every step has clear status, reason, impact, and next action.
• No step exposes raw technical form sprawl by default.
• Safety status and restore proof are visible where needed.
• Preview is summary-first, not item-flood-first.
• Confirmation is high-friction and proof-safe.

Safety

• No false recovery proof.
• No false execution proof.
• No false post-run evidence.
• No unsafe progression through required mappings or validation blockers.
• Provider credential failure is product-safe, not 500.

UX

• Mapping details hidden by default.
• Resolver is clear when expanded.
• Group picker keeps restore context.
• Long lists use tables/collapsed sections.
• No repeated helper copy.
• No clipped status badges.
• No generic primary CTAs that lose context.

Technical

• RestoreRunCreatePresenter remains single source of truth.
• No process-level static memoization.
• Blade components render contract state only.
• No new backend model/migration.
• No new packages/assets.
• RBAC/capability behavior preserved.

Validation

• Required feature tests pass.
• Required browser tests pass.
• Screenshots captured.
• Pint passes.
• git diff --check passes.
• Full suite status honestly reported if run/not run.

Success Criteria

• SC-001: A reviewer can inspect each wizard step and identify the visible status, reason, impact, proof basis, blocker, and next action within five seconds.
• SC-002: Required tests prove no false pre-execution recovery, execution proof, or post-run evidence claims.
• SC-003: Browser screenshots cover the nine required states in the Spec 333 artifact directory or document unreachable states with repo-truth reasons.
• SC-004: No application diff outside the Restore Create UI/test/screenshot scope is required for implementation.

Required Browser Screenshots

Save under specs/333-restore-create-ux-final-productization/artifacts/screenshots/:

1. 01-step-1-backup-selected.png
2. 02-step-2-scope-default.png
3. 03-step-2-resolver-expanded.png
4. 04-step-2-group-picker-results.png
5. 05-step-2-group-picker-empty.png
6. 06-step-3-validation-blocked.png
7. 07-step-3-validation-passed.png
8. 08-step-4-preview-generated.png
9. 09-step-5-confirm-ready.png

If a state is not reachable, the implementation close-out must document why.

Follow-Up Spec Candidates

Do not include these in Spec 333:

• Restore Run Detail / Post-Execution Proof Productization (number TBD; 334-* already exists in this repo)
• Baseline Compare Product Process Flow Alignment (number TBD)
• Evidence Path Product Process Flow Alignment (number TBD)
• Provider Readiness Productization (number TBD)