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

Tasks: Spec 333 - Restore Create UX Final Productization

Input: specs/333-restore-create-ux-final-productization/spec.md, specs/333-restore-create-ux-final-productization/plan.md, specs/333-restore-create-ux-final-productization/restore-create-state-contract.md

Tests: Required. This spec changes an existing high-risk Filament/Livewire wizard and must include Feature/Livewire, Unit presenter determinism, and Browser smoke/screenshot coverage.

Test Governance Checklist

• Lane assignment is named and is the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in the smallest honest family, and browser additions are explicit.
• Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
• Planned validation commands cover the change without pulling in unrelated lane cost.
• The dangerous-workflow/browser-smoke surface profile is explicit.
• Any material budget, baseline, trend, or escalation note is recorded in the active spec or PR.

Phase 1: Repo Truth and State Contract

Purpose: Confirm Spec 333 is display/productization over Spec 332, not a new architecture.

• T001 Re-read specs/333-restore-create-ux-final-productization/spec.md, specs/333-restore-create-ux-final-productization/plan.md, specs/333-restore-create-ux-final-productization/tasks.md, and specs/333-restore-create-ux-final-productization/restore-create-state-contract.md.
• T002 Re-read Spec 332 artifacts in specs/332-product-process-flow-system-v1/spec.md, specs/332-product-process-flow-system-v1/plan.md, and specs/332-product-process-flow-system-v1/tasks.md.
• T003 Inspect existing Restore Create surfaces before editing: apps/platform/app/Filament/Resources/RestoreRunResource.php, apps/platform/app/Filament/Resources/RestoreRunResource/Pages/CreateRestoreRun.php, and apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php.
• T004 Inspect existing Restore Create views under apps/platform/resources/views/filament/forms/components/restore-run-*.blade.php and group picker views apps/platform/resources/views/livewire/entra-group-cache-picker-table.blade.php and apps/platform/resources/views/filament/modals/entra-group-cache-picker.blade.php.
• T005 Confirm RestoreRunCreatePresenter remains the single source of truth for status, reason, impact, primary next action, gates, proof items, mapping summary, validation summary, preview summary, can-continue, blocked reason, and diagnostics state.
• T006 Confirm no static process-level memoization or fixture state leakage exists in RestoreRunCreatePresenter; document any issue in implementation notes before changing runtime.
• T007 Confirm implementation will not add migrations, models, packages, assets, env vars, queues, scheduler changes, storage changes, Graph calls, provider gateway behavior, or a new flow system.

Phase 2: Tests First - Presenter and Step Contracts

Purpose: Add focused tests before or alongside UI changes.

• T008 [P] Create apps/platform/tests/Feature/Filament/Spec333RestoreCreateUxFinalProductizationTest.php with Step 1-5 rendering and forbidden-copy coverage.
• T009 [P] Extend apps/platform/tests/Unit/Filament/RestoreRunCreatePresenterDeterminismTest.php for no static memoization, independent fixture state, metadata-only backup not leaking into usable backup state, and mapping state isolation.
• T010 [P] Extend apps/platform/tests/Feature/RestoreGroupMappingTest.php for mapping row identity, cached target label, manual fallback label, skip state, current-environment group cache, empty cache, and no hardcoded workspace IDs.
• T011 [P] Extend apps/platform/tests/Feature/Filament/RestoreWizardGraphSafetyTest.php for provider credential missing blocked state, product-safe validation copy, no raw provider/Graph exception, and no 500.
• T012 [P] Extend apps/platform/tests/Feature/Filament/RestoreRunPreviewProductizationTest.php for summary-first preview, needs-attention first, unchanged items collapsed/compact, no stale validation next-gate copy, and raw details behind disclosure.

Phase 3: Step 1 - Select Backup Set Polish

Purpose: Make source usability clear before restore scope/validation.

• T013 Update apps/platform/app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php display-only contract output as needed so no-backup state shows Source required, reason, impact, and primary next action Select backup set.
• T014 Update RestoreRunCreatePresenter source-state output so unusable backup with no captured/restorable items shows Source not usable, safe reason, impact, and primary next action Select another backup set.
• T015 Update RestoreRunCreatePresenter source-state output so usable degraded/mapping issue state shows review-required copy without implying execution safety.
• T016 Update RestoreRunCreatePresenter source-state output so clean usable backup state shows Source selected and primary next action Continue to scope.
• T017 Update apps/platform/resources/views/filament/forms/components/restore-run-safety-decision.blade.php only if needed to render the contract without adding independent gate/proof logic.
• T018 Update apps/platform/resources/views/filament/forms/components/restore-run-backup-quality-summary.blade.php so required quality counts and caveat are visible and no forbidden copy appears.
• T019 Verify Step 1 still renders full Restore Safety Gates via apps/platform/resources/views/filament/forms/components/restore-run-safety-gates.blade.php and Restore Proof via apps/platform/resources/views/filament/forms/components/restore-run-proof-aside.blade.php.

Phase 4: Step 2 - Scope, Mapping Resolver, Group Picker

Purpose: Keep Step 2 calm by default and make dependency resolution operator-safe.

• T020 Update apps/platform/resources/views/filament/forms/components/restore-run-scope-summary.blade.php to show scope options, scope impact, next safety gate, mapping summary, and Resolve mappings without exposing raw mapping rows by default.
• T021 Ensure Step 2 default hides full mapping details, full safety gates, repeated GUID helper text, and raw IDs as primary labels in apps/platform/app/Filament/Resources/RestoreRunResource.php.
• T022 Update RestoreRunCreatePresenter mapping summary output as needed to expose resolved, unresolved, skipped, manual fallback count, and required-before-validation copy.
• T023 Update apps/platform/resources/views/filament/forms/components/restore-run-mapping-resolver-summary.blade.php so expanded resolver mode shows Resolve target mappings, progress summary, and exactly one collapse action.
• T024 Update mapping row rendering in apps/platform/app/Filament/Resources/RestoreRunResource.php so source group display name is primary, source ID is secondary metadata, and Unknown source group fallback is allowed only with Source ID: {id}.
• T025 Update mapping helper/rendering so cached target display name is primary, target ID is secondary, and manual GUID entry is labeled Manual fallback.
• T026 Preserve explicit skip behavior in apps/platform/app/Filament/Resources/RestoreRunResource.php and apps/platform/resources/views/filament/forms/components/restore-run-group-mapping-skipped.blade.php, or update spec/plan first if repo truth proves skip is unsupported.
• T027 Update apps/platform/resources/views/livewire/entra-group-cache-picker-table.blade.php and apps/platform/app/Livewire/EntraGroupCachePickerTable.php so group picker results are scoped to the current environment and hide cross-workspace/environment groups.
• T028 Update apps/platform/resources/views/filament/modals/entra-group-cache-picker.blade.php and picker table empty state so no-cache copy, Open group sync, View group sync operations, and manual fallback are task-specific, context-safe, and open secondary flows in new tabs.
• T029 Verify group picker URLs use active workspace/environment context and no hardcoded numeric workspace IDs or 404 links.
• T030 Verify Next remains blocked when unresolved required mappings exist and the blocked copy is Required before validation can run.

Phase 5: Step 3 - Validation Productization

Purpose: Make validation states product-safe and gate-correct.

• T031 Update RestoreRunCreatePresenter validation summary output as needed for no-checks, provider-credentials-missing, blockers, warnings, and clean states.
• T032 Update apps/platform/resources/views/filament/forms/components/restore-run-checks.blade.php so blockers, warnings, and safe checks are grouped and diagnostics remain collapsed.
• T033 Update validation notification copy in apps/platform/app/Filament/Resources/RestoreRunResource.php so blockers never show Safety checks completed; use Safety checks finished with blockers or equivalent.
• T034 Ensure provider credentials missing shows Validation blocked with product-safe copy and Review provider connection action, without raw provider credential/Graph exception.
• T035 Verify Step 3 does not display forbidden terms: Graph works again, Technical startability, write-gate, hard-blocker, raw Provider credential exception, or raw Graph exception.
• T036 Verify Step 3 Next remains blocked when provider readiness or validation blockers exist.

Phase 6: Step 4 - Preview Productization

Purpose: Make Preview summary-first and gate-consistent.

• T037 Update RestoreRunCreatePresenter preview summary output as needed to expose total reviewed, changed, unchanged, needs review, assignments changed, scope tags changed, blockers, warnings, and next gate.
• T038 Update apps/platform/resources/views/filament/forms/components/restore-run-preview.blade.php so the restore preview decision summary appears before item details.
• T039 Update preview rendering so Needs attention is visible first, changed items are grouped, unchanged/no-change items are collapsed or compact, and all reviewed items remain available behind disclosure.
• T040 Ensure raw diff JSON, raw provider payload, and repeated item-card labels are hidden by default.
• T041 Fix preview next-gate copy so preview-current state shows validation complete, preview complete, and next gate confirmation required.
• T042 Fix preview blocked/not-generated copy so validation-required, blocker, and generate-preview states are accurate and do not show stale resolve technical blockers copy when preview is current.

Phase 7: Step 5 - Confirmation Productization

Purpose: Preserve high friction and proof-safe execution copy.

• T043 Update RestoreRunCreatePresenter confirmation/readiness output as needed so confirmation shows preview summary, execution readiness, and proof-safe pre-execution warnings.
• T044 Update apps/platform/resources/views/filament/forms/components/restore-run-confirm-panel.blade.php to show confirmation decision summary, dry-run/preview-only state, high-friction acknowledgement, and proof-safe copy.
• T045 Ensure apps/platform/app/Filament/Resources/RestoreRunResource.php keeps execution unavailable until required mappings resolved or explicitly skipped, validation not blocked, preview current, confirmation satisfied, and existing RBAC/capability permits execution.
• T046 Verify Confirm does not claim recovery verified, execution proof complete, post-run evidence available, customer-safe, healthy, or fully restored before execution and proof exist.

Phase 8: Browser Screenshots

Purpose: Prove visible states required by Spec 333.

• T047 Create apps/platform/tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php using existing Spec 332 browser conventions where possible.
• T048 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/01-step-1-backup-selected.png.
• T049 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/02-step-2-scope-default.png.
• T050 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/03-step-2-resolver-expanded.png.
• T051 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/04-step-2-group-picker-results.png.
• T052 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/05-step-2-group-picker-empty.png.
• T053 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/06-step-3-validation-blocked.png.
• T054 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/07-step-3-validation-passed.png.
• T054a Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/07-step-3-validation-passed-dark.png.
• T055 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/08-step-4-preview-generated.png.
• T056 Capture specs/333-restore-create-ux-final-productization/artifacts/screenshots/09-step-5-confirm-ready.png.
• T057 If a screenshot state is not reachable, document the repo-truth reason in specs/333-restore-create-ux-final-productization/tasks.md close-out before marking validation complete.

Phase 9: Final Validation

Purpose: Prove the bounded implementation and report honestly.

• T058 Run 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.
• T059 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php --compact.
• T060 Run cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec332 --compact if shared Spec 332 presenter/components changed.
• T061 Run cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec332* --compact if shared Spec 332 browser-covered components changed.
• T062 Run cd apps/platform && ./vendor/bin/sail pint --dirty.
• T063 Run git diff --check.
• T064 Report full suite status honestly if not run.
• T065 Confirm no migrations, models, packages, assets, env vars, queues, scheduler, storage, provider gateway behavior, Graph calls, new presenter, or new flow system were added.

Close-out Evidence

• Lane assignment: focused Feature/Livewire + Unit presenter determinism + Browser smoke/screenshot coverage for a dangerous restore-create workflow.
• Existing RestoreGroupMappingTest.php and RestoreWizardGraphSafetyTest.php already covered the requested group-picker/provider-safety surfaces; Spec 333 adds direct Step 1-5 productization coverage in Spec333RestoreCreateUxFinalProductizationTest.php.
• Follow-up enterprise UI review adjustments: Step 1 now keeps the selected backup source as the primary decision, clean backup quality renders as Available, the create-wizard header uses compact fixed-width step pills with explicit light/dark surface separation and Filament --primary-* tokens, and Step 1 safety gates/proof are collapsed into a compact evidence summary instead of rendering full evidence surfaces by default.
• Step 2 follow-up productization: scope now starts with a compact decision bar, the separate Resolve mappings CTA was removed, the Resolve target mappings section is the central mapping work area, restore gates/proof are collapsed into Step 2 Restore evidence, raw object IDs moved behind details, and Skip assignment uses warning treatment with explicit consequence copy.
• Step 3 follow-up productization: validation now renders a compact Validation decision, provider-credential blocked state hides Run checks and shows only repair guidance plus Review provider connection, passed validation summarizes blockers/warnings/safe checks with safe details collapsed, stale helper text was replaced by state-aware copy, validation gates/proof are collapsed into Validation evidence, and light/dark surfaces have tested card/background separation.
• Step 4 follow-up productization: preview now leads with Preview evidence, reads next gate/CTA/execution state from the central wizard_gate contract, allows confirmation review when preview evidence is current while real execution prerequisites remain unavailable, switches the hint action to Regenerate preview after evidence exists, keeps safety gates and restore proof behind a closed View safety gates and restore proof disclosure, removes the competing visible Restore safety status rail from the preview step, shows per-policy Restore action, Policy diff, Assignments, Scope tags, Review reason, and Action evidence in Preview details, renders diff parts as semantic chips (added success, removed danger, changed warning), and keeps warning/diff surfaces readable in dark mode.
• Environment note: Sail could not run because Docker was not running, so equivalent local PHP/Pest commands were used.
• Validation run: cd apps/platform && php artisan test tests/Feature/Filament/Spec333RestoreCreateUxFinalProductizationTest.php tests/Feature/Filament/Spec332ProductProcessFlowSystemTest.php tests/Feature/Filament/RestoreRunPreviewProductizationTest.php tests/Unit/Filament/RestoreRunCreatePresenterDeterminismTest.php --compact passed: 28 tests, 441 assertions.
• Adjacent safety run: cd apps/platform && php artisan test tests/Feature/RestoreGroupMappingTest.php tests/Feature/Filament/RestoreWizardGraphSafetyTest.php --compact passed: 7 tests, 66 assertions.
• Browser run: cd apps/platform && php vendor/bin/pest tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php --compact passed: 6 tests, 169 assertions.
• Browser screenshot/shared-flow run: cd apps/platform && php vendor/bin/pest tests/Browser/Spec332RestoreRunWizardProductProcessFlowSmokeTest.php tests/Browser/Spec332RestoreRunWizardProductProcessFlowScreenshotsTest.php --compact passed: 13 tests, 208 assertions.
• Formatting: cd apps/platform && vendor/bin/pint app/Filament/Resources/RestoreRunResource.php app/Filament/Resources/RestoreRunResource/Presenters/RestoreRunCreatePresenter.php tests/Feature/Filament/Spec333RestoreCreateUxFinalProductizationTest.php tests/Feature/Filament/Spec332ProductProcessFlowSystemTest.php tests/Feature/Filament/RestoreRunPreviewProductizationTest.php tests/Browser/Spec333RestoreCreateUxFinalProductizationSmokeTest.php tests/Browser/Spec332RestoreRunWizardProductProcessFlowSmokeTest.php passed.
• Whitespace: git diff --check passed.
• Screenshot artifacts captured: 01-step-1-backup-selected.png, 02-step-2-scope-default.png, 03-step-2-resolver-expanded.png, 04-step-2-group-picker-results.png, 05-step-2-group-picker-empty.png, 06-step-3-validation-blocked.png, 07-step-3-validation-passed.png, 07-step-3-validation-passed-dark.png, 08-step-4-preview-generated.png, 09-step-5-confirm-ready.png, 10-step-4-preview-execution-prerequisites-unavailable.png, and 11-step-5-execution-prerequisites-locked.png.
• Scope confirmation: no migrations, models, packages, assets, env vars, queues, scheduler changes, storage changes, Graph calls, provider gateway behavior changes, new presenter, or new flow system were added.

Dependencies

• Phase 1 blocks all runtime edits.
• Phase 2 should be completed before or alongside Phases 3-7.
• Phases 3-7 may be worked in focused slices but must preserve presenter-contract truth.
• Phase 8 requires runtime UI states from Phases 3-7.
• Phase 9 closes the spec.

Parallel Work Examples

• T008, T009, T010, T011, and T012 can be drafted in parallel because they target different test files.
• Step 1 view polish and Step 3 validation copy can be reviewed independently if they do not change shared presenter keys.
• Browser screenshot capture must wait until the visible states exist.

Explicit Non-Goals

• NT001 Do not create a new Product Process Flow architecture.
• NT002 Do not create a new Restore Create presenter.
• NT003 Do not rewrite restore backend behavior.
• NT004 Do not change OperationRun model semantics.
• NT005 Do not change ProviderGateway behavior or add Graph calls.
• NT006 Do not create migrations or model changes.
• NT007 Do not add packages, assets, env vars, queues, scheduler, or storage changes.
• NT008 Do not productize Restore Run Detail or post-execution result pages in this spec.
• NT009 Do not migrate Baseline Compare, Evidence path, Customer Review, or other surfaces into Product Process Flow in this spec.
• NT010 Do not introduce false recovery-proof, execution-proof, post-run evidence, health, compliance, or customer-safe claims.