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

# Research: Operations Naming Consolidation

## Decision 1: Update shared label emitters first, then patch remaining local copy

- **Decision**: Treat `OperationRunLinks`, `OperationUxPresenter`, `OperationRunCompleted`, `OperationRunQueued`, `RelatedActionLabelCatalog`, `RelatedNavigationResolver`, `ReferenceTypeLabelCatalog`, and `OperationRunReferenceResolver` as the primary change points for deep-link labels and identifiers.
- **Rationale**: Repo analysis shows that these helpers feed multiple notifications, related-navigation affordances, reference summaries, and embedded viewers. Updating them first removes the largest source of naming drift without inventing a new naming layer.
- **Alternatives considered**: Patch every visible `View run` and `Run #...` string independently. Rejected because shared helpers would continue emitting drift into newly touched surfaces.

## Decision 2: Preserve internal `run` implementation names and route helpers

- **Decision**: Keep existing class names, route names, action names such as `view_run`, route slugs, and enum values intact, while changing only operator-visible labels, titles, and helper copy.
- **Rationale**: The spec explicitly forbids internal renames, and a naming-only slice should not widen into compatibility or refactor work.
- **Alternatives considered**: Rename internal helpers and route slugs to `operation`. Rejected because it would create unnecessary migration and regression risk outside the current release truth.

## Decision 3: Keep Spec 170 system-plane behavior out of scope while protecting against shared-helper regressions

- **Decision**: Leave `/system/ops/*` interaction semantics under Spec 170 ownership and only accept indirect system-plane copy changes if a shared helper already used by both slices requires it.
- **Rationale**: Spec 170 already aligned visible `Operations` / `Operation` naming and interaction semantics on the dedicated system pages. Spec 171 is about residual drift elsewhere.
- **Alternatives considered**: Re-open the system pages inside Spec 171. Rejected because it would overlap active scope and blur ownership between the two specs.

## Decision 4: Preserve workflow verbs where they describe starting work, not an existing record

- **Decision**: Keep verbs such as `Start verification` and bootstrap-progress wording when they describe initiating work, but require `Open operation`, `Operation ID`, and `Operation #...` when the UI references an already-created `OperationRun` record.
- **Rationale**: Verification and onboarding surfaces currently mix task language with record language. The operator needs both concepts, but they must not collapse into the same ambiguous `run` noun.
- **Alternatives considered**: Replace every visible use of `run` with `operation`, including workflow verbs. Rejected because the spec explicitly allows task-oriented verbs when they describe initiating new work.

## Decision 5: Update plural summary copy in place instead of introducing a presenter or taxonomy

- **Decision**: Adjust existing builders and Blade views such as `WorkspaceOverviewBuilder`, `BaselineCompareSummaryAssessor`, `ManagedTenantOnboardingWizard`, `resources/views/filament/pages/monitoring/operations.blade.php`, and tenant summary widgets directly.
- **Rationale**: The slice is about copy consistency, not about inventing a new cross-domain explanation layer. Direct updates satisfy `ABSTR-001` and `LAYER-001`.
- **Alternatives considered**: Introduce a reusable naming presenter or a pluralization catalog just for operation copy. Rejected because one concrete noun family does not justify a new abstraction.

## Decision 6: Use representative rendered-surface tests instead of a global string-ban guard

- **Decision**: Update focused unit, feature, Livewire, and browser tests that already render the affected links, summaries, and embedded reports.
- **Rationale**: Valid uses of `run` still exist internally and in workflow-verb contexts. The constitution prefers business-truth assertions over thin indirection or over-broad grep-style guards.
- **Alternatives considered**: Add an architecture test that forbids `View run`, `Run ID`, or `Run #` repo-wide. Rejected because it would either fail on valid contexts or require an exception list that encodes the same drift the slice is meant to simplify.

## Decision 7: Record the route and embedded-surface naming expectations in an OpenAPI-style contract

- **Decision**: Add `contracts/operation-naming-surface-contract.yaml` to capture existing route targets, identifier-label rules, embedded verification expectations, and plural-summary guidance.
- **Rationale**: The planning workflow expects a concrete contract artifact, and this feature benefits from a machine-readable record of which route targets and visible labels are considered canonical without inventing a new JSON API.
- **Alternatives considered**: Skip `contracts/` because no API route changes are introduced. Rejected because the route/UI contract is still central to the implementation and review workflow.