# 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.
