# Tasks: Deferred Operator Surfaces Retrofit **Input**: Design documents from `specs/172-deferred-operator-surfaces-retrofit/` **Prerequisites**: `plan.md`, `spec.md`, `research.md`, `data-model.md`, `contracts/embedded-operation-surface-contract.yaml`, `quickstart.md` **Tests**: Required. Update the focused Pest coverage listed in `specs/172-deferred-operator-surfaces-retrofit/quickstart.md`. **Operations**: Reuse the existing `OperationRun` lifecycle and canonical `/admin/operations` routes; this feature must not add new run semantics. **RBAC**: Authorization planes and 404/403 behavior stay unchanged; covered surfaces still need access-aware advanced links. ## Phase 1: Setup (Shared Context) **Purpose**: Confirm the retrofit boundary, affected surfaces, and focused verification targets before implementation starts. - [X] T001 Review the implementation boundary in `specs/172-deferred-operator-surfaces-retrofit/spec.md`, `specs/172-deferred-operator-surfaces-retrofit/plan.md`, `specs/172-deferred-operator-surfaces-retrofit/research.md`, and `specs/172-deferred-operator-surfaces-retrofit/contracts/embedded-operation-surface-contract.yaml` - [X] T002 Baseline the current tenant-detail and onboarding behavior in `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`, `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, and `tests/Feature/Onboarding/OnboardingVerificationTest.php` --- ## Phase 2: Foundational (Blocking Prerequisites) **Purpose**: Put the shared route and CTA handoff in place before changing individual surfaces. **⚠️ CRITICAL**: No user story work should start until this phase is complete. - [X] T003 Update shared destination metadata in `app/Support/OperationRunLinks.php` so retrofitted surfaces can keep canonical collection/detail routes while making any broader admin scope explicit - [X] T004 Establish page-level workflow-action ownership in `app/Filament/Resources/TenantResource/Pages/ViewTenant.php` and `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` so embedded surfaces consume inspect-oriented inputs instead of deciding workflow CTAs themselves **Checkpoint**: Shared helpers and page-level state handoff are ready, so story work can proceed safely. --- ## Phase 3: User Story 1 - Tenant Detail Drill-Ins Preserve Tenant Context (Priority: P1) 🎯 MVP **Goal**: Make the tenant-detail recent-operations and verification widgets expose one clear primary CTA per state without silently broadening scope. **Independent Test**: Render the tenant-detail widgets and verify that row-level or current-run inspection stays primary, any collection drill-in is clearly secondary, and the visible scope remains truthful before navigation. ### Tests for User Story 1 - [X] T005 [P] [US1] Update `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php` to assert row-level `Open operation` links stay primary and any collection drill-in is secondary and scope-explicit - [X] T006 [P] [US1] Update `tests/Feature/Filament/TenantVerificationReportWidgetTest.php` to assert `Start verification` and `Open operation` never appear as competing peer CTAs on the widget ### Implementation for User Story 1 - [X] T007 [US1] Refine state assembly in `app/Filament/Widgets/Tenant/RecentOperationsSummary.php` and `app/Filament/Widgets/Tenant/TenantVerificationReport.php` so each tenant-detail surface emits one primary CTA contract per state - [X] T008 [P] [US1] Update `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php` to demote any collection affordance and make broader admin scope explicit before navigation - [X] T009 [P] [US1] Update `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php` to render one primary CTA per state and rely on the tenant-detail header action for reruns **Checkpoint**: Tenant-detail embedded operation surfaces are independently testable and preserve tenant context truth. --- ## Phase 4: User Story 2 - Onboarding And Verification Surfaces Expose One Clear Operation Path (Priority: P1) **Goal**: Keep onboarding verification workflow controls authoritative while report and technical-details surfaces expose one primary inspect path plus diagnostics-secondary links only. **Independent Test**: Render onboarding verification surfaces in no-run, active-run, and completed-run states and verify that each state exposes exactly one primary CTA while previous-run or advanced monitoring links remain secondary and access-aware. ### Tests for User Story 2 - [X] T010 [P] [US2] Update `tests/Feature/Onboarding/OnboardingVerificationTest.php` to assert one primary verification CTA per onboarding state - [X] T011 [P] [US2] Update `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php` and `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php` to assert previous-run and advanced monitoring links stay diagnostics-secondary and access-aware ### Implementation for User Story 2 - [X] T012 [US2] Refine onboarding verification report payload assembly in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` so current-run, previous-run, and advanced-link data reach the embedded surfaces without introducing inline workflow CTAs - [X] T013 [P] [US2] Update `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php` to show exactly one primary current-run inspect CTA when a run exists and otherwise render explanatory empty-state content without inline workflow CTAs - [X] T014 [P] [US2] Update `resources/views/filament/modals/onboarding-verification-technical-details.blade.php` to keep previous-run and advanced monitoring links secondary, explicitly labeled, and diagnostics-only **Checkpoint**: Onboarding verification surfaces are independently testable and expose a single clear operator path per state. --- ## Phase 5: User Story 3 - Retrofitted Deferred Surfaces Gain Explicit Governance (Priority: P2) **Goal**: Replace blanket deferred-surface treatment for the retrofitted operation-bearing surfaces with explicit governance and representative automated coverage. **Independent Test**: Run the guard suite and confirm that tenant-detail and onboarding verification surfaces are covered explicitly, while unrelated deferred surfaces remain intentional non-goals. ### Tests for User Story 3 - [X] T015 [P] [US3] Update `tests/Feature/Guards/ActionSurfaceContractTest.php` to assert tenant-detail and onboarding verification surfaces are covered explicitly rather than by blanket deferred exemptions ### Implementation for User Story 3 - [X] T016 [US3] Narrow retrofit governance in `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php` so only true non-goal deferred surfaces remain exempt and dedicated coverage is documented for `ManagedTenantOnboardingWizard` **Checkpoint**: Governance now protects the retrofitted surfaces without sweeping unrelated deferred pages into scope. --- ## Phase 6: Polish & Cross-Cutting Concerns **Purpose**: Run the focused regression and cleanup steps needed to ship the retrofit safely. - [X] T017 Run the focused regression suite in `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `tests/Feature/Filament/TenantVerificationReportWidgetTest.php`, `tests/Feature/Onboarding/OnboardingVerificationTest.php`, `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php`, `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php` - [X] T018 Run formatting for `app/Support/OperationRunLinks.php`, `app/Filament/Resources/TenantResource/Pages/ViewTenant.php`, `app/Filament/Widgets/Tenant/RecentOperationsSummary.php`, `app/Filament/Widgets/Tenant/TenantVerificationReport.php`, `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, and `app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php` - [X] T019 Execute the manual validation checklist in `specs/172-deferred-operator-surfaces-retrofit/quickstart.md` against `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php`, `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php`, `resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php`, and `resources/views/filament/modals/onboarding-verification-technical-details.blade.php` - [X] T020 Verify render-path constraints in `app/Filament/Widgets/Tenant/RecentOperationsSummary.php`, `app/Filament/Widgets/Tenant/TenantVerificationReport.php`, `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, and `app/Support/OperationRunLinks.php` so the retrofit stays DB-only at render time, adds no remote calls or queued work, does not alter polling cadence, and does not broaden query fan-out --- ## Dependencies & Execution Order ### Phase Dependencies - **Phase 1: Setup** has no dependencies and starts immediately. - **Phase 2: Foundational** depends on Phase 1 and blocks all story work. - **Phase 3: User Story 1** depends on Phase 2. - **Phase 4: User Story 2** depends on Phase 2. - **Phase 5: User Story 3** depends on the relevant US1 and US2 implementation and test coverage being in place. - **Phase 6: Polish** depends on the desired story phases being complete. ### User Story Dependencies - **US1** can start as soon as T003-T004 are complete. - **US2** can start as soon as T003-T004 are complete. - **US3** should start after US1 and US2 have landed their representative surface behavior, because the governance guard needs the final retrofit boundary. ### Parallel Opportunities - **US1**: T005 and T006 can run in parallel; after T007, T008 and T009 can run in parallel. - **US2**: T010 and T011 can run in parallel; after T012, T013 and T014 can run in parallel. - **US3**: Parallelism is intentionally limited; create the failing guard in T015 first, then narrow the exemption set in T016. --- ## Parallel Example: User Story 1 ```bash # Run the tenant-detail widget tests together: Task: "T005 [US1] Update tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php" Task: "T006 [US1] Update tests/Feature/Filament/TenantVerificationReportWidgetTest.php" # After widget state assembly is updated, align both Blade views together: Task: "T008 [US1] Update resources/views/filament/widgets/tenant/recent-operations-summary.blade.php" Task: "T009 [US1] Update resources/views/filament/widgets/tenant/tenant-verification-report.blade.php" ``` ## Parallel Example: User Story 2 ```bash # Update onboarding coverage together: Task: "T010 [US2] Update tests/Feature/Onboarding/OnboardingVerificationTest.php" Task: "T011 [US2] Update tests/Feature/Onboarding/OnboardingVerificationClustersTest.php and tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php" # After the wizard state contract is ready, update both onboarding views together: Task: "T013 [US2] Update resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php" Task: "T014 [US2] Update resources/views/filament/modals/onboarding-verification-technical-details.blade.php" ``` ## Parallel Example: User Story 3 ```bash # No safe implementation pair is recommended here; land the failing guard first, then narrow the exemption baseline: Task: "T015 [US3] Update tests/Feature/Guards/ActionSurfaceContractTest.php" Task: "T016 [US3] Update app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php" ``` --- ## Implementation Strategy ### MVP First (User Story 1 Only) 1. Complete T001-T004. 2. Complete T005-T009. 3. Validate tenant-detail behavior with the focused US1 tests before moving on. ### Incremental Delivery 1. Complete Setup and Foundational work to lock the shared route and CTA contract. 2. Deliver US1 and validate tenant-detail scope truth. 3. Deliver US2 and validate onboarding CTA hierarchy. 4. Deliver US3 to replace blanket exemptions with explicit governance. 5. Finish with T017-T020. ### Parallel Team Strategy 1. One developer completes T001-T004. 2. After Phase 2, one developer can take US1 while another takes US2. 3. Once both surfaces are stable, finish US3 governance and the shared regression pass. --- ## Notes - `[P]` tasks touch different files and can run in parallel. - User story labels map directly to the priorities and acceptance criteria in `specs/172-deferred-operator-surfaces-retrofit/spec.md`. - Keep the implementation narrow: no new routes, persistence, capabilities, assets, or `OperationRun` lifecycle changes.