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.