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:

```bash
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:

```bash
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:

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

## Formatting

After code changes, run:

```bash
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.