TenantAtlas/specs/171-operations-naming-consolidation/quickstart.md

Quickstart: Operations Naming Consolidation

Goal

Align non-system operator-visible references to existing OperationRun records so shared links, identifiers, embedded verification/onboarding surfaces, and summary/helper copy use Operations / Operation consistently without changing routes, capabilities, or operation behavior.

Prerequisites

1. Start the local stack:

vendor/bin/sail up -d

2. Work on branch 171-operations-naming-consolidation.

Implementation Steps

1. Update the shared label emitters first:
   • app/Support/OperationRunLinks.php
   • app/Support/OpsUx/OperationUxPresenter.php
   • app/Notifications/OperationRunCompleted.php
   • app/Notifications/OperationRunQueued.php
   • app/Support/Navigation/RelatedActionLabelCatalog.php
   • app/Support/Navigation/RelatedNavigationResolver.php
   • app/Support/References/ReferenceTypeLabelCatalog.php
   • app/Support/References/Resolvers/OperationRunReferenceResolver.php
2. Update representative non-system Filament pages, resources, and widgets that still render local run terminology:
   • app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
   • app/Filament/Widgets/Tenant/TenantVerificationReport.php
   • app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
   • app/Filament/Resources/BackupScheduleResource.php
   • app/Filament/Resources/BackupSetResource.php
   • app/Filament/Resources/EvidenceSnapshotResource.php
   • app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
   • app/Support/Baselines/BaselineCompareSummaryAssessor.php
   • app/Support/Workspaces/WorkspaceOverviewBuilder.php
3. Update the covered Blade views and embedded report partials:
   • resources/views/filament/widgets/tenant/tenant-verification-report.blade.php
   • resources/views/filament/components/verification-report-viewer.blade.php
   • resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
   • resources/views/filament/modals/onboarding-verification-technical-details.blade.php
   • resources/views/filament/widgets/tenant/recent-operations-summary.blade.php
   • resources/views/filament/pages/monitoring/operations.blade.php
4. Keep Spec 170 system pages unchanged unless a shared-helper copy update requires a small regression assertion adjustment; do not re-open their interaction model in this slice.
5. Run a final search for residual View run, Run ID, Run #, and plural runs collection wording such as Open all runs, and leave only valid internal or explicitly out-of-scope matches.

Tests To Update

1. Unit coverage for shared navigation and reference emitters:
   • tests/Unit/Support/RelatedNavigationResolverTest.php
   • tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php
2. Feature coverage for shared notifications, representative viewers, verification surfaces, and summary widgets:
   • tests/Feature/OpsUx/NotificationViewRunLinkTest.php
   • tests/Feature/Operations/TenantlessOperationRunViewerTest.php
   • tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php
   • tests/Feature/Filament/TenantVerificationReportWidgetTest.php
   • tests/Feature/Onboarding/OnboardingVerificationTest.php
   • tests/Feature/Onboarding/OnboardingVerificationClustersTest.php
   • tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php
   • tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php
   • tests/Feature/Filament/WorkspaceOverviewContentTest.php
   • tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
   • tests/Feature/Monitoring/OperationLifecycleAggregateVisibilityTest.php
   • tests/Feature/Guards/ActionSurfaceContractTest.php
3. Browser coverage for onboarding/bootstrap summary wording when the embedded report changes:
   • tests/Browser/OnboardingDraftRefreshTest.php
4. System-surface regression coverage whenever shared emitters or cross-panel operation labels change:
   • tests/Feature/System/Spec114/OpsTriageActionsTest.php
   • tests/Feature/System/Spec114/OpsFailuresViewTest.php
   • tests/Feature/System/Spec114/OpsStuckViewTest.php

Focused Verification

Run the smallest relevant regression set first:

vendor/bin/sail artisan test --compact tests/Unit/Support/RelatedNavigationResolverTest.php
vendor/bin/sail artisan test --compact tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php
vendor/bin/sail artisan test --compact tests/Feature/OpsUx/NotificationViewRunLinkTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
vendor/bin/sail artisan test --compact tests/Feature/Operations/TenantlessOperationRunViewerTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.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/Filament/BaselineCompareSummaryConsistencyTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/WorkspaceOverviewContentTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php
vendor/bin/sail artisan test --compact tests/Feature/Monitoring/OperationLifecycleAggregateVisibilityTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsTriageActionsTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsFailuresViewTest.php
vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/OpsStuckViewTest.php

If onboarding/bootstrap copy changes are touched, add:

vendor/bin/sail artisan test --compact tests/Browser/OnboardingDraftRefreshTest.php

Formatting

After code changes, run:

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

Manual Review Checklist

1. Covered links to existing records use the canonical operation action label for that surface, including Open operation where the contract fixes it, instead of View run.
2. Covered identifiers say Operation #... or Operation ID instead of Run #... or Run ID.
3. Verification and onboarding surfaces still use task verbs such as Start verification when starting new work.
4. Covered summary/helper copy uses plural operations when referring to existing historical records.
5. The tenantless admin operation viewer uses Operation terminology without changing its route target.
6. Spec 170 system pages still keep their existing aligned Operations / Operation semantics and interaction model.
7. No route slug, class name, enum value, capability, or persistence artifact was renamed.