TenantAtlas/specs/172-deferred-operator-surfaces-retrofit/quickstart.md

Quickstart: Deferred Operator Surfaces Retrofit

Goal

Retrofit the tenant-detail and onboarding embedded operation surfaces so they present one clear primary action per state, keep scope truthful before navigation, and leave existing OperationRun routes, authorization, and lifecycle behavior unchanged.

Prerequisites

1. Start the local stack:

vendor/bin/sail up -d

2. Work on branch 172-deferred-operator-surfaces-retrofit.

Implementation Steps

1. Align the tenant-detail embedded surfaces first:
   • app/Filament/Resources/TenantResource/Pages/ViewTenant.php
   • app/Filament/Widgets/Tenant/RecentOperationsSummary.php
   • resources/views/filament/widgets/tenant/recent-operations-summary.blade.php
   • app/Filament/Widgets/Tenant/TenantVerificationReport.php
   • resources/views/filament/widgets/tenant/tenant-verification-report.blade.php
   • app/Support/OperationRunLinks.php only if a secondary collection affordance needs clearer admin-scope copy
2. Make the CTA hierarchy explicit on tenant detail:
   • recent-operations summary keeps row-level inspect links primary and any collection link secondary
   • verification widget uses Start verification only when no run exists and relies on the existing tenant-detail header action for reruns once a run exists
3. Align the onboarding verification surfaces without changing workflow semantics:
   • app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
   • resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
   • resources/views/filament/modals/onboarding-verification-technical-details.blade.php
   • keep the wizard's existing next-step controls (Start verification, Refresh) authoritative
   • keep current-run inspect links singular and keep previous-run/monitoring links diagnostics-secondary only
4. Narrow the governance story instead of creating a new framework:
   • update app/Support/Ui/ActionSurface/ActionSurfaceExemptions.php only if the baseline reason needs to become more specific
   • update tests/Feature/Guards/ActionSurfaceContractTest.php if the exemption or dedicated-conformance expectation changes
5. Re-run a final pass over the covered views to ensure there is no equal-weight combination of:
   • collection CTA plus row/detail CTA on the same embedded summary
   • Start verification plus Open operation inside the same tenant-detail widget state
   • Open operation, Open previous operation, and Open operation in Monitoring (advanced) all appearing as peer actions on the onboarding report surface

Tests To Update

1. Tenant-detail embedded surface coverage:
   • tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
   • tests/Feature/Filament/TenantVerificationReportWidgetTest.php
2. Onboarding verification coverage:
   • tests/Feature/Onboarding/OnboardingVerificationTest.php
   • tests/Feature/Onboarding/OnboardingVerificationClustersTest.php
   • tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
3. Governance coverage:
   • tests/Feature/Guards/ActionSurfaceContractTest.php

Focused Verification

Run the narrow regression set first:

vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/TenantVerificationReportWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationClustersTest.php
vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php

If the implementation touches shared operation-link wording or helper text used outside the immediate surfaces, run the smallest additional focused tests that render those helpers.

Formatting

After code changes, run:

vendor/bin/sail bin pint --dirty --format agent

Manual Review Checklist

1. The tenant-detail recent-operations summary does not present a header-level collection link with the same visual weight as row-level inspect links.
2. The tenant verification widget shows Start verification only when no current run exists and otherwise shows one primary inspect link for the current run.
3. The onboarding flow keeps one workflow-next-step control per state and does not present current-run, previous-run, and advanced-monitoring links as peer primary actions.
4. Any remaining broader-scope operations collection link makes that broader admin scope explicit through context or nearby copy.
5. Any remaining advanced monitoring/admin link is visibly secondary and only appears when the operator can access that destination.
6. No route, capability, persistence artifact, provider registration, or OperationRun lifecycle behavior changed.