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

Implementation Plan: Spec 333 - Restore Create UX Final Productization

• Branch: 333-restore-create-ux-final-productization
• Date: 2026-05-26
• Spec: specs/333-restore-create-ux-final-productization/spec.md
• Input: Productize Restore Create wizard UX over Spec 332 foundation. No new flow system, presenter, or backend rewrite.

Summary

Finalize the visible Restore Create wizard as a coherent restore safety workflow:

• Step 1: source decision, backup quality, full gates, proof.
• Step 2: calm scope summary, mapping summary by default, explicit resolver mode, group picker context.
• Step 3: product-safe validation, grouped blockers/warnings/safe checks, provider credential blocked state.
• Step 4: summary-first preview, needs-attention first, compact unchanged detail, gate-consistent next step.
• Step 5: high-friction confirmation, dry-run clarity, proof-safe pre-execution copy.

Implementation must consume Spec 332 state truth from RestoreRunCreatePresenter and existing Product Process Flow components. It must not add backend behavior, persistence, Graph calls, packages, or new architecture.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0
Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1
Storage: Existing PostgreSQL-backed models only; no migration
Testing: Pest Feature/Livewire, Unit, and Browser
Validation Lanes: confidence + browser + formatting
Target Platform: Laravel Sail local, Dokploy container runtime for staging/production
Project Type: Laravel monolith with Filament admin panel
Performance Goals: keep wizard rendering DB/local-state based; no Graph calls during render; long lists collapsed/compact
Constraints: no new packages, no migrations, no queues/scheduler/storage/env changes, no new Product Process Flow system
Scale/Scope: one existing environment-bound Restore Create wizard and its focused tests/screenshots

Repo Truth Summary

Existing foundation:

• Presenter source of truth: apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php
• Wizard/page entry: apps/platform/app/Filament/Resources/RestoreRunResource.php
• Create page wrapper: apps/platform/app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php
• Restore Create components:
  • apps/platform/resources/views/filament/forms/components/restore-run-safety-decision.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-backup-quality-summary.blade.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-scope-summary.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-mapping-resolver-summary.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-checks.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-preview.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-confirm-panel.blade.php
  • apps/platform/resources/views/filament/forms/components/restore-run-group-mapping-skipped.blade.php
  • apps/platform/resources/views/filament/forms/components/partials/restore-run-process-flow-panel.blade.php
  • apps/platform/resources/views/filament/forms/components/partials/restore-run-proof-panel.blade.php
• Group picker:
  • apps/platform/app/Livewire/EntraGroupCachePickerTable.php
  • apps/platform/resources/views/livewire/entra-group-cache-picker-table.blade.php
  • apps/platform/resources/views/filament/modals/entra-group-cache-picker.blade.php
• Existing related tests:
  • apps/platform/tests/Feature/Filament/Spec332ProductProcessFlowSystemTest.php
  • apps/platform/tests/Browser/Spec332RestoreRunWizardProductProcessFlowSmokeTest.php
  • apps/platform/tests/Browser/Spec332RestoreRunWizardProductProcessFlowScreenshotsTest.php
  • apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php
  • apps/platform/tests/Feature/Filament/RestoreWizardGraphSafetyTest.php
  • apps/platform/tests/Feature/RestoreGroupMappingTest.php
  • apps/platform/tests/Unit/Filament/RestoreRunCreatePresenterDeterminismTest.php

UI / Surface Guardrail Plan

• Guardrail scope: changed surfaces
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • Restore Create wizard at /admin/workspaces/{workspace}/environments/{environment}/restore-runs/create
  • Step 1 source decision state
  • Step 2 scope/mapping resolver state
  • group picker modal
  • Step 3 validation state
  • Step 4 preview state
  • Step 5 confirmation/execution readiness state
• No-impact class, if applicable: N/A
• Native vs custom classification summary: mixed Filament wizard/forms/actions plus existing custom Blade components
• Shared-family relevance: Product Process Flow, proof panels, status messaging, action links, dangerous confirmation
• State layers in scope: page, wizard step, presenter contract, modal, Livewire table
• Audience modes in scope: operator-MSP and support-platform; no customer-facing route added
• Decision/diagnostic/raw hierarchy plan: decision first, proof second, diagnostics/raw third/collapsed
• Raw/support gating plan: raw IDs secondary, raw payloads/diffs collapsed or behind disclosure
• One-primary-action / duplicate-truth control: presenter contract owns status/reason/impact/next-action; Blade renders it without computing alternate truth
• Handling modes by drift class or surface: review-mandatory because this is a dangerous workflow
• Repository-signal treatment: review-mandatory for restore/gating/proof copy
• Special surface test profiles: dangerous workflow wizard + browser smoke
• Required tests or manual smoke: focused Feature/Livewire, Unit presenter determinism, Browser screenshots
• Exception path and spread control: none planned
• Active feature PR close-out entry: Smoke Coverage
• UI/Productization coverage decision: existing route/archetype coverage remains valid; Spec 333 screenshots provide focused coverage
• Coverage artifacts to update: none unless implementation discovers route/archetype/coverage drift
• No-impact rationale: N/A
• Navigation / Filament provider-panel handling: no panel/provider registration change
• Screenshot or page-report need: screenshots required, page report not required unless drift is discovered

Shared Pattern & System Fit

• Cross-cutting feature marker: yes
• Systems touched: Restore Create wizard, Product Process Flow, Restore Proof, status messaging, group picker, validation/preview/confirmation panels
• Shared abstractions reused: RestoreRunCreatePresenter, existing restore-run Blade components, BadgeRenderer, OperationRunLinks, restore safety/preview/check integrity resolvers
• New abstraction introduced? why?: none
• Why the existing abstraction was sufficient or insufficient: sufficient; Spec 332 intentionally centralized the product-state contract and Product Process Flow
• Bounded deviation / spread control: display-only tweaks may stay in existing components but cannot calculate independent gate/proof truth

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: presentation only
• Central contract reused: existing restore execution behavior and OperationRunLinks
• Delegated UX behaviors: existing start/completion/notification behavior remains unchanged
• Surface-owned behavior kept local: restore inputs, dry-run/preview-only toggle, typed confirmation, pre-execution proof copy
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception path: none

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: yes, display-only
• Provider-owned seams: Entra group cache, Microsoft/provider connection readiness
• Platform-core seams: environment, restore scope, proof basis, operation proof, post-run evidence
• Neutral platform terms / contracts preserved: environment, provider connection, restore scope, target mapping, operation proof, post-run evidence
• Retained provider-specific semantics and why: directory group and object ID wording remains where the existing Entra group mapping boundary requires it
• Bounded extraction or follow-up path: broader provider readiness productization deferred to follow-up

Constitution Check

GATE: Must pass before implementation. Re-check after implementation.

• Inventory-first / snapshots-second: pass; Restore Create uses existing backup snapshots and restore draft state.
• Read/write separation: pass; preview/dry-run and explicit confirmation remain required before execution.
• Graph contract path: pass; no new Graph calls. Existing Graph behavior remains behind existing services/contracts.
• Deterministic capabilities: pass; existing capability checks remain authoritative.
• RBAC-UX: pass; no UI-only authorization changes. Existing server-side authorization/capability checks remain required.
• Workspace/tenant isolation: pass; existing route-bound workspace/environment context remains in force; group picker must use current environment cache only.
• Run observability / OperationRun UX: pass; no new OperationRun behavior.
• Test governance: pass; lane classification is explicit and bounded.
• Proportionality / no premature abstraction: pass; no new presenter, framework, persistence, enum, taxonomy, or backend layer.
• Provider boundary: pass; provider-specific wording remains only at existing provider-owned group/provider seams.
• Filament-native UI: pass with existing mixed custom components; implementation must keep Filament semantics and no ad-hoc styling system.
• UI/Productization coverage: pass; reachable UI changes are classified and screenshots are required.

Test Governance Check

• Test purpose / classification by changed surface:
  • Unit: presenter determinism and no static memoization/leakage.
  • Feature/Livewire: wizard state, copy, gating, grouped validation, preview summary, confirmation readiness.
  • Browser: visible multi-step workflow and screenshots.
• Affected validation lanes: confidence + browser.
• Why this lane mix is the narrowest sufficient proof: Restore Create is a Livewire wizard with browser-visible behavior and high-risk state gates; pure unit/feature tests alone cannot prove visible layout/screenshot requirements.
• Narrowest proving 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
• Fixture / helper / factory / seed / context cost risks: use existing Spec 332 browser fixtures/helpers where possible; do not create broad shared defaults.
• Expensive defaults or shared helper growth introduced?: no planned shared default growth.
• Heavy-family additions, promotions, or visibility changes: explicit Spec 333 browser smoke only.
• Surface-class relief / special coverage rule: no standard relief; dangerous workflow requires browser smoke/screenshots.
• Closing validation and reviewer handoff: run targeted Feature/Unit/Browser tests, Spec 332 overlap tests, Pint dirty, and git diff --check; report full suite if not run.
• Budget / baseline / trend follow-up: none expected unless browser fixture runtime materially grows.
• Review-stop questions: lane fit, breadth, hidden fixture cost, browser screenshot reliability, no false proof copy.
• Escalation path: document-in-feature.
• Active feature PR close-out entry: Smoke Coverage.
• Why no dedicated follow-up spec is needed: this is bounded final productization of one existing wizard; post-execution proof belongs to a separate follow-up.

Project Structure

Documentation (this feature)

specs/333-restore-create-ux-final-productization/
├── spec.md
├── plan.md
├── tasks.md
├── restore-create-state-contract.md
├── checklists/
│   └── requirements.md
└── artifacts/
    └── screenshots/
        └── .gitkeep

Source Code (expected implementation surfaces)

apps/platform/app/Filament/Resources/
├── RestoreRunResource.php
└── RestoreRunResource/
    ├── Pages/CreateRestoreRun.php
    └── Presenters/RestoreRunCreatePresenter.php

apps/platform/resources/views/filament/forms/components/
├── restore-run-safety-decision.blade.php
├── restore-run-backup-quality-summary.blade.php
├── restore-run-safety-gates.blade.php
├── restore-run-proof-aside.blade.php
├── restore-run-scope-summary.blade.php
├── restore-run-mapping-resolver-summary.blade.php
├── restore-run-checks.blade.php
├── restore-run-preview.blade.php
├── restore-run-confirm-panel.blade.php
└── restore-run-group-mapping-skipped.blade.php

apps/platform/resources/views/livewire/
└── entra-group-cache-picker-table.blade.php

apps/platform/resources/views/filament/modals/
└── entra-group-cache-picker.blade.php

Test Code (expected implementation surfaces)

apps/platform/tests/Feature/Filament/Spec333RestoreCreateUxFinalProductizationTest.php
apps/platform/tests/Feature/RestoreGroupMappingTest.php
apps/platform/tests/Feature/Filament/RestoreWizardGraphSafetyTest.php
apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php
apps/platform/tests/Unit/Filament/RestoreRunCreatePresenterDeterminismTest.php
apps/platform/tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php

Domain / Model Implications

• No model changes.
• No migration.
• No new restore backend behavior.
• No new OperationRun type.
• No provider gateway change.
• Existing RestoreRun, BackupSet, BackupItem, EntraGroup, ManagedEnvironment, provider connection, validation, and preview state remain the data sources.

UI / Filament Implications

• Filament v5 / Livewire v4.1 compliance remains required.
• Panel provider registration remains unchanged in apps/platform/bootstrap/providers.php; no new panel/provider.
• RestoreRunResource keeps existing View page; global search behavior is not changed by this spec and must be verified if touched.
• Destructive/high-impact behavior is not changed. Real restore execution remains gated by existing dry-run/preview, validation, confirmation, authorization, and audit behavior.
• No registered Filament assets are planned, so no new filament:assets deployment step is introduced.

Implementation Phases

Phase 1 - State Contract / Repo Truth

• Re-read Spec 332 artifacts, current presenter/components, and this Spec 333 state contract.
• Confirm RestoreRunCreatePresenter is the single source of truth.
• Confirm no static/process-level memoization.
• Update runtime only after state contract alignment is clear.

Phase 2 - Step 1 Polish

• Align Step 1 source states to required copy.
• Ensure backup quality summary exposes required counts and caveat.
• Keep full gates and proof panel visible.
• Remove internal/technical/false-proof copy.

Phase 3 - Step 2 Scope / Mapping / Group Picker

• Keep default Step 2 calm and summary-first.
• Hide mapping details by default.
• Productize resolver row identity and single collapse action.
• Preserve or explicitly state skip behavior.
• Make group picker context and empty states current-environment safe.
• Keep Next blocked by unresolved mappings.

Phase 4 - Step 3 Validation

• Group blockers, warnings, and safe checks.
• Make provider credentials missing a product-safe blocked state.
• Fix toast copy when blockers exist.
• Keep next state-aware and blocked when validation is blocked.

Phase 5 - Step 4 Preview

• Make preview summary-first.
• Show needs attention first.
• Collapse or compact unchanged/no-change items.
• Hide raw diff/provider payload by default.
• Correct next-gate copy for current/blocked/not-generated states.

Phase 6 - Step 5 Confirmation

• Make confirmation high-friction.
• Make dry-run/preview-only state clear.
• Show pre-execution operation proof and post-run evidence as unavailable.
• Ensure execute availability remains controlled by existing gates and capability behavior.

Phase 7 - Tests / Browser / Screenshots

• Add or adjust focused Feature/Unit tests.
• Add browser smoke and screenshots.
• Run targeted validation commands.
• Re-run Spec 332 overlap tests if shared components changed.

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
./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec332* --compact
./vendor/bin/sail pint --dirty
git diff --check

Rollout / Deployment Considerations

• Migrations: none.
• Environment variables: none.
• Queues/workers: none.
• Scheduler: none.
• Storage/volumes: none.
• Packages/assets: none.
• Dokploy/Staging/Production: ordinary app deployment only; validate on Staging because restore is high-risk UI.
• Filament assets: no new registered assets planned; if implementation unexpectedly registers assets, deployment must include cd apps/platform && php artisan filament:assets and this plan must be updated first.

Risk Controls

• Do not implement a new flow system or presenter.
• Do not move truth into Blade.
• Do not add backend restore behavior.
• Do not overclaim recovery, operation proof, post-run evidence, health, or customer safety.
• Do not use raw IDs as primary labels.
• Do not expose raw provider errors/payloads by default.
• Do not broaden tests into unrelated surfaces.
• Update spec/plan before implementation if repo truth differs from assumptions.