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.

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

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

• 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

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

• 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

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

• 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

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

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

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

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

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.