ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
671abbed53
TenantAtlas/specs/172-deferred-operator-surfaces-retrofit/tasks.md
ahmido 671abbed53 feat: retrofit deferred operator surfaces (#203) 
## Summary
- retrofit the tenant detail recent-operations and verification surfaces to keep one clear primary inspect path per state
- keep onboarding workflow actions on the wizard step while moving previous-run and advanced monitoring links into diagnostics-only technical details
- add focused spec 172 design artifacts, feature coverage, and a dedicated browser smoke test for the deferred operator surface retrofit

## Testing
- `vendor/bin/sail artisan test --compact tests/Browser/Spec172DeferredOperatorSurfacesSmokeTest.php tests/Browser/OnboardingDraftRefreshTest.php tests/Browser/OnboardingDraftVerificationResumeTest.php`

## Notes
- base branch: `dev`
- branch head: `172-deferred-operator-surfaces-retrofit`
- browser smoke pack passed locally after the final changes

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #203
2026-04-02 09:22:44 +00:00

12 KiB
Raw Blame History

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.

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

  • 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
  • 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

  • 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
  • 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

  • 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
  • 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
  • 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

  • T010 [P] [US2] Update tests/Feature/Onboarding/OnboardingVerificationTest.php to assert one primary verification CTA per onboarding state
  • 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

  • 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
  • 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
  • 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

  • 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

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

  • 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
  • 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
  • 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
  • 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

# 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

# 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

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