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

# Tasks: Operations Naming Consolidation

**Input**: Design documents from `/specs/171-operations-naming-consolidation/`
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/operation-naming-surface-contract.yaml

**Tests**: Runtime behavior changes in this repo require Pest coverage. Each story below includes focused regression work before implementation is considered complete.

**Organization**: Tasks are grouped by user story so each story can be implemented and validated independently after the shared naming emitters are stabilized.

## Phase 1: Setup

**Purpose**: Lock the implementation targets to the generated plan artifacts before runtime edits begin.

- [X] T001 Reconfirm the implementation and verification targets in `specs/171-operations-naming-consolidation/contracts/operation-naming-surface-contract.yaml` and `specs/171-operations-naming-consolidation/quickstart.md` before editing runtime files.
- [X] T002 Inspect the current naming-drift touchpoints in `app/Support/OperationRunLinks.php`, `app/Support/OpsUx/OperationUxPresenter.php`, `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php`, and `resources/views/filament/pages/monitoring/operations.blade.php` so every shared/root copy source is mapped before editing.

---

## Phase 2: Foundational

**Purpose**: Establish the shared regression baseline and canonical label emitters that all story work depends on.

**⚠️ CRITICAL**: No user story work should be considered complete until these shared expectations and emitters are updated.

- [X] T003 Update the shared terminology baseline in `tests/Unit/Support/RelatedNavigationResolverTest.php`, `tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php`, `tests/Feature/OpsUx/NotificationViewRunLinkTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php` so canonical operation action labels and identifiers are enforced according to `specs/171-operations-naming-consolidation/contracts/operation-naming-surface-contract.yaml` before surface-specific edits begin.
- [X] T004 [P] Implement canonical link and action labels in `app/Support/OperationRunLinks.php`, `app/Support/Navigation/RelatedActionLabelCatalog.php`, and `app/Support/Navigation/RelatedNavigationResolver.php` so shared deep-link affordances stop emitting `View run` wording.
- [X] T005 [P] Implement canonical identifier, reference, and notification copy in `app/Support/References/ReferenceTypeLabelCatalog.php`, `app/Support/References/Resolvers/OperationRunReferenceResolver.php`, `app/Support/OpsUx/OperationUxPresenter.php`, `app/Notifications/OperationRunCompleted.php`, and `app/Notifications/OperationRunQueued.php` so shared emitters consistently describe existing records as operations.
- [X] T006 Run the shared-helper regression pack for `tests/Unit/Support/RelatedNavigationResolverTest.php`, `tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php`, `tests/Feature/OpsUx/NotificationViewRunLinkTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php` before moving on to story-specific surfaces.

**Checkpoint**: Shared naming emitters and regression guards are stable; user story surfaces can now be updated independently.

---

## Phase 3: User Story 1 - Shared Operation Links Use One Vocabulary (Priority: P1) 🎯 MVP

**Goal**: Make representative non-system viewers, resources, and related record affordances present existing `OperationRun` records with one canonical `Operation` vocabulary.

**Independent Test**: Render the tenantless viewer and representative backup/evidence reference surfaces and verify visible labels use canonical operation action labels and identifiers, including `Open operation` where the contract fixes it, rather than `View run`, `Run #`, or `Run ID`.

### Tests for User Story 1

- [X] T007 [US1] Add failing viewer and related-record assertions in `tests/Feature/Operations/TenantlessOperationRunViewerTest.php` and `tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php` for canonical operation action labels and `Operation #...` or `Operation ID` copy.

### Implementation for User Story 1

- [X] T008 [P] [US1] Update canonical viewer wording in `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` and `app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php` so existing record titles and helper text use `Operation` terminology.
- [X] T009 [P] [US1] Update related operation reference copy in `app/Filament/Resources/BackupScheduleResource.php`, `app/Filament/Resources/BackupSetResource.php`, and `app/Filament/Resources/EvidenceSnapshotResource.php` so embedded resource affordances use canonical operation labels and identifiers.
- [X] T010 [US1] Run the focused US1 regression pack for `tests/Feature/Operations/TenantlessOperationRunViewerTest.php` and `tests/Feature/Filament/BackupSetResolvedReferencePresentationTest.php`.

**Checkpoint**: Shared links and representative non-system record viewers use one canonical operation vocabulary.

---

## Phase 4: User Story 2 - Verification Surfaces Distinguish Workflow Verbs From Operation Records (Priority: P1)

**Goal**: Keep workflow verbs such as `Start verification` for new work while making verification and onboarding report surfaces name the resulting persisted record as an operation.

**Independent Test**: Render the tenant verification widget and representative onboarding verification surfaces, then verify workflow CTAs keep task verbs while persisted record links, identifiers, and empty states use `Operation` terminology.

### Tests for User Story 2

- [X] T011 [US2] Add failing verification and onboarding wording assertions in `tests/Feature/Filament/TenantVerificationReportWidgetTest.php`, `tests/Feature/Onboarding/OnboardingVerificationTest.php`, `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php`, `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php`, and `tests/Browser/OnboardingDraftRefreshTest.php` so task verbs remain intact while historical records use `Operation` wording.

### Implementation for User Story 2

- [X] T012 [P] [US2] Update verification widget wording in `app/Filament/Widgets/Tenant/TenantVerificationReport.php` and `resources/views/filament/widgets/tenant/tenant-verification-report.blade.php` so `Start verification` stays task-oriented while record links and empty-state copy use `Operation` terminology.
- [X] T013 [P] [US2] Update embedded verification report copy in `resources/views/filament/components/verification-report-viewer.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` so identifiers and drill-ins use `Operation` wording.
- [X] T014 [US2] Update onboarding flow wording in `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` so workflow verbs remain task-based while persisted record references and helper copy use `Operation` or `Operations` consistently.
- [X] T015 [US2] Run the focused US2 regression pack for `tests/Feature/Filament/TenantVerificationReportWidgetTest.php`, `tests/Feature/Onboarding/OnboardingVerificationTest.php`, `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php`, `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php`, and `tests/Browser/OnboardingDraftRefreshTest.php`.

**Checkpoint**: Verification and onboarding surfaces distinguish new work from existing operation records without ambiguous `run` terminology.

---

## Phase 5: User Story 3 - Summary Surfaces Use Consistent Operation Plurals (Priority: P2)

**Goal**: Make summary and health surfaces describe failed, stuck, active, or recent historical records as operations so high-frequency helper copy matches the canonical destinations.

**Independent Test**: Render representative baseline, monitoring, workspace, and tenant summary surfaces and verify plural helper text uses `operations` rather than `runs` when describing existing `OperationRun` history.

### Tests for User Story 3

- [X] T016 [US3] Add failing plural-summary assertions in `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php`, `tests/Feature/Monitoring/OperationLifecycleAggregateVisibilityTest.php`, `tests/Feature/Filament/WorkspaceOverviewContentTest.php`, and `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php` so summary nouns must use `operations` for historical records.

### Implementation for User Story 3

- [X] T017 [P] [US3] Update summary helper copy in `app/Support/Baselines/BaselineCompareSummaryAssessor.php` and `app/Support/Workspaces/WorkspaceOverviewBuilder.php` so historical record counts and guidance are described as operations.
- [X] T018 [P] [US3] Update rendered summary copy in `resources/views/filament/widgets/tenant/recent-operations-summary.blade.php` and `resources/views/filament/pages/monitoring/operations.blade.php` so plural nouns and drill-in labels align with `Operations` terminology.
- [X] T019 [US3] Run the focused US3 regression pack for `tests/Feature/Filament/BaselineCompareSummaryConsistencyTest.php`, `tests/Feature/Monitoring/OperationLifecycleAggregateVisibilityTest.php`, `tests/Feature/Filament/WorkspaceOverviewContentTest.php`, and `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`.

**Checkpoint**: Summary and health copy reinforces the same `Operations / Operation` vocabulary as the linked detail surfaces.

---

## Phase 6: Polish & Cross-Cutting Concerns

**Purpose**: Final cleanup and verification across all stories.

- [X] T020 Run a residual copy sweep in `app/`, `resources/views/`, and `tests/` for `View run`, `Run ID`, `Run #`, and plural `runs` collection wording such as `Open all runs`, then confirm any remaining matches are internal, workflow-verb, or explicitly out of scope under `specs/171-operations-naming-consolidation/spec.md`.
- [X] T021 Run formatting with `vendor/bin/sail bin pint --dirty --format agent` for the `app/`, `resources/views/`, and `tests/` files touched by `specs/171-operations-naming-consolidation/quickstart.md`.
- [X] T022 Run the consolidated focused verification pack from `specs/171-operations-naming-consolidation/quickstart.md`, including `tests/Unit/Support/RelatedNavigationResolverTest.php`, `tests/Unit/Support/References/RelatedContextReferenceAdapterTest.php`, `tests/Feature/OpsUx/NotificationViewRunLinkTest.php`, `tests/Feature/Guards/ActionSurfaceContractTest.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`, and `tests/Browser/OnboardingDraftRefreshTest.php` when onboarding copy changed.
- [X] T023 Run the explicit Spec 170/shared-helper regression guard for `tests/Feature/System/Spec114/OpsTriageActionsTest.php`, `tests/Feature/System/Spec114/OpsFailuresViewTest.php`, and `tests/Feature/System/Spec114/OpsStuckViewTest.php` so shared naming changes do not regress aligned `/system/ops/*` surfaces.
- [X] T024 Validate the final behavior against `specs/171-operations-naming-consolidation/contracts/operation-naming-surface-contract.yaml` and `specs/171-operations-naming-consolidation/quickstart.md` before handoff.

---

## Dependencies & Execution Order

### Phase Dependencies

- **Setup (Phase 1)**: No dependencies.
- **Foundational (Phase 2)**: Depends on Setup and establishes the shared regression baseline plus shared naming emitters.
- **User Story 1 (Phase 3)**: Depends on Foundational.
- **User Story 2 (Phase 4)**: Depends on Foundational.
- **User Story 3 (Phase 5)**: Depends on Foundational and should follow the P1 stories in delivery order, but it does not require new behavior from US1 or US2 beyond the shared emitters completed in Phase 2.
- **Polish (Phase 6)**: Depends on the desired user stories being complete.

### User Story Dependencies

- **US1**: Independent after Phase 2; it only changes representative viewer and related-record surfaces.
- **US2**: Independent after Phase 2; it only changes verification and onboarding surfaces while reusing the shared emitters.
- **US3**: Independent after Phase 2; it only changes summary/helper copy and related coverage.

### Within Each User Story

- Update story-specific tests first and make them fail for the intended behavior.
- Apply the runtime changes next.
- Run the smallest focused verification pack before moving on.

---

## Parallel Opportunities

- T004 and T005 can run in parallel because they modify different shared file groups after T003 lands.
- T008 and T009 can run in parallel because they touch different representative viewer/resource files inside US1.
- T012 and T013 can run in parallel because they split verification-widget work from embedded-report Blade partials inside US2.
- T017 and T018 can run in parallel because they split summary builders from rendered summary views inside US3.

---

## Parallel Example: Foundational

```bash
Task: "T004 Implement canonical link and action labels in app/Support/OperationRunLinks.php, app/Support/Navigation/RelatedActionLabelCatalog.php, and app/Support/Navigation/RelatedNavigationResolver.php"
Task: "T005 Implement canonical identifier, reference, and notification copy in app/Support/References/ReferenceTypeLabelCatalog.php, app/Support/References/Resolvers/OperationRunReferenceResolver.php, app/Support/OpsUx/OperationUxPresenter.php, app/Notifications/OperationRunCompleted.php, and app/Notifications/OperationRunQueued.php"
```

---

## Parallel Example: User Story 2

```bash
Task: "T012 Update verification widget wording in app/Filament/Widgets/Tenant/TenantVerificationReport.php and resources/views/filament/widgets/tenant/tenant-verification-report.blade.php"
Task: "T013 Update embedded verification report copy in resources/views/filament/components/verification-report-viewer.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"
```

---

## Parallel Example: User Story 3

```bash
Task: "T017 Update summary helper copy in app/Support/Baselines/BaselineCompareSummaryAssessor.php and app/Support/Workspaces/WorkspaceOverviewBuilder.php"
Task: "T018 Update rendered summary copy in resources/views/filament/widgets/tenant/recent-operations-summary.blade.php and resources/views/filament/pages/monitoring/operations.blade.php"
```

---

## Implementation Strategy

### MVP First (Foundational + User Story 1)

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1.
4. Validate the shared emitters plus representative viewer/resource surfaces before expanding into verification and summary copy.

### Incremental Delivery

1. Finish Setup + Foundational to lock the shared naming baseline.
2. Deliver US1 to normalize representative viewer and related-record language.
3. Deliver US2 to separate workflow verbs from persisted operation-record nouns on verification/onboarding surfaces.
4. Deliver US3 to align high-frequency summary and helper copy with the same vocabulary.
5. Run Phase 6 polish checks and hand off.

### Parallel Team Strategy

1. One engineer updates the shared test baseline in T003.
2. After T003:
   - Engineer A can take T004.
   - Engineer B can take T005.
3. After Phase 2:
   - Engineer A can take US1.
   - Engineer B can take US2.
   - Engineer C can prepare US3 if the team wants to batch the P2 copy follow-up.

---

## Notes

- `[P]` tasks touch different files and have no unfinished dependencies.
- Story labels map directly to the three user stories in `spec.md`.
- This feature intentionally avoids route renames, capability changes, provider registration changes, global-search changes, and persistence changes.
- Spec 170 remains authoritative for aligned `/system/ops/*` surfaces; only shared-helper regressions may require incidental attention during implementation.