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

# Feature Specification: Operations Naming Consolidation

**Feature Branch**: `171-operations-naming-consolidation`  
**Created**: 2026-03-30  
**Status**: Draft  
**Input**: User description: "Operations Naming Consolidation"

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + tenant + canonical-view + platform
- **Primary Routes**:
  - `/admin/operations`
  - `/admin/operations/{run}`
  - `/admin/t/{tenant}`
  - `/system/ops/runs/{run}`
- **Data Ownership**:
  - No new platform-owned, workspace-owned, or tenant-owned records are introduced
  - Existing `OperationRun` records remain the only source of truth for operation history, status, and deep-link destinations
  - Existing notifications, related-navigation payloads, reference summaries, and embedded report components remain derived presentation layers only
- **RBAC**:
  - No new capability, role, or authorization plane is introduced
  - Existing admin, tenant, and platform route guards remain authoritative for whether an operator may open a given operation destination
  - This feature changes visible operator vocabulary only; it does not widen access to any operation route or action

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| Surface | Surface Type | Primary Inspect/Open Model | Row Click | Secondary Actions Placement | Destructive Actions Placement | Canonical Collection Route | Canonical Detail Route | Scope Signals | Canonical Noun | Critical Truth Visible by Default | Exception Type |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Shared operation links and related navigation | Embedded related-navigation affordance | Explicit safe link to one existing operation | n/a | inline or footer placement only | none | panel-appropriate operations list | panel-appropriate operation detail | current panel and current scope remain legible | Operations / Operation | destination label, operation identity, scope cue | none |
| Tenantless/admin operation detail viewers | Detail-first Operational Surface | Dedicated detail page | forbidden | detail header or related-links group only | detail header only | `/admin/operations` or `/system/ops/runs` | panel-appropriate operation detail route | workspace or platform context explicit | Operations / Operation | operation identity, outcome, context, next navigation | none |
| Verification and onboarding operation report surfaces | Embedded operator detail panel | One primary CTA to the existing operation when present | forbidden | low-emphasis advanced links only when justified | none | panel-appropriate operations list when needed | panel-appropriate operation detail route | tenant/workspace context and verification context visible | Operations / Operation | verification status, operation identity, recency | none |
| Summary and health widgets that reference operations | Embedded status summary | Explicit single CTA or passive summary with no competing link | forbidden | card footer or summary action only | none | panel-appropriate operations list | panel-appropriate operation detail route when singular | current scope stays explicit | Operations / Operation | counts, status family, scope | none |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|
| Shared operation links and related navigation | Workspace, tenant, or platform operator | Embedded related-navigation affordance | Which operation does this link open? | explicit `Operation` noun, stable verb, scope cue when needed | raw route names or internal type strings stay hidden | navigation context only | none | `Open operation` or route-equivalent collection navigation | none |
| Tenantless/admin operation detail viewers | Workspace or platform operator | Detail-first Operational Surface | What happened on this operation? | operation title, `Operation #<id>`, outcome, scope, next steps | extended payloads and traces stay in diagnostics sections | execution outcome, lifecycle, operability | existing detail-owned actions only | existing detail navigation and triage actions | existing detail-owned destructive actions only |
| Verification and onboarding operation report surfaces | Workspace or tenant operator | Embedded operator detail panel | What verification operation ran, and how do I inspect it? | verification state, operation identity, timestamp, one primary link | low-level JSON, hashes, and raw provider details stay behind explicit reveal | verification status, operation recency | none | `Open operation`, workflow-native next-step CTA such as `Start verification` | none |
| Summary and health widgets that reference operations | Workspace, tenant, or platform operator | Embedded status summary | Are there failed, stuck, or recent operations I should inspect? | pluralized operation labels, counts, scope, one clear drill-in | raw IDs and detailed traces stay on destination surfaces | count state, health family, recency | none | collection drill-in or none | none |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: No
- **New persisted entity/table/artifact?**: No
- **New abstraction?**: No
- **New enum/state/reason family?**: No
- **New cross-domain UI framework/taxonomy?**: No
- **Current operator problem**: Outside the system-panel surfaces already aligned by Spec 170, the repo still exposes `View run`, `Run ID`, `Run #...`, and plural `runs` wording across notifications, related links, verification reports, admin viewers, and health widgets, which makes the same `OperationRun` record look like different domain objects depending on where the operator encounters it.
- **Existing structure is insufficient because**: Shared label catalogs, reference resolvers, and embedded components still permit local wording drift, so isolated copy fixes would keep reintroducing inconsistent nouns.
- **Narrowest correct implementation**: Standardize only operator-visible naming for existing `OperationRun` record references outside Spec 170, reuse the existing routes and destinations, and update the shared label-producing layers that feed multiple surfaces.
- **Ownership cost**: Existing feature and guard tests will need wording updates, and a small number of embedded report components will need representative coverage so naming drift does not return.
- **Alternative intentionally rejected**: Renaming PHP classes, route slugs, enum values, or persistence structures was rejected because this slice is about operator-visible language, not internal refactoring.
- **Release truth**: Current-release truth. The inconsistent labels already exist in the repo today across tenant, workspace, canonical-view, and platform surfaces.

## User Scenarios & Testing *(mandatory)*

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

As an operator, I want every link to an existing operation record to use the same noun and verb pattern, so that I immediately recognize it as the same destination regardless of which page, widget, or notification I came from.

**Why this priority**: Shared deep-link labels are the highest-leverage root cause because they feed many surfaces at once.

**Independent Test**: Can be fully tested by rendering representative resources, widgets, shared related-navigation payloads, and notifications that link to existing operation records, then asserting that visible labels use `Open operation` and `Operation #<id>` or `Operation ID` rather than `View run`, `Run #`, or `Run ID`.

**Acceptance Scenarios**:

1. **Given** a resource, widget, or notification exposes a link to an existing operation, **When** the operator sees that affordance, **Then** the visible action uses `Operation` terminology rather than `run` terminology.
2. **Given** a shared reference or related-navigation summary exposes an operation identifier, **When** it renders, **Then** the visible identifier uses `Operation #<id>` or `Operation ID` rather than `Run #<id>` or `Run ID`.

---

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

As a workspace or tenant operator, I want verification and onboarding surfaces to keep workflow verbs like `Start verification` while naming the resulting historical record as an operation, so that the current task and the inspectable record are not collapsed into one ambiguous `run` concept.

**Why this priority**: Verification widgets, modals, and onboarding reports currently mix workflow language and operation-record language most visibly.

**Independent Test**: Can be fully tested by rendering representative verification and onboarding report surfaces and asserting that workflow actions keep their intended verbs while record links and identifiers use `Operation` terminology.

**Acceptance Scenarios**:

1. **Given** a verification surface offers the operator a next step, **When** the action starts new work, **Then** it may continue to use a task verb such as `Start verification`.
2. **Given** a verification surface shows a historical or in-progress operation record, **When** the operator inspects the metadata or opens the destination, **Then** the visible link and identifier use `Operation` terminology rather than `run` terminology.
3. **Given** no verification-backed operation exists yet, **When** the empty state renders, **Then** the explanation avoids using `run` as a fallback noun for the future record.

---

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

As an operator scanning health and summary surfaces, I want counts and helper text to refer to failed, stuck, or recent operations consistently, so that summary cards and widgets reinforce the same vocabulary as detailed destinations.

**Why this priority**: Summary copy is lower-risk than deep-link labels, but it is high-frequency and shapes daily operator language.

**Independent Test**: Can be fully tested by rendering representative summary widgets or health indicators and asserting that plural copy uses `operations` instead of `runs` when referring to existing `OperationRun` records.

**Acceptance Scenarios**:

1. **Given** a summary widget describes failed or stuck execution records, **When** it renders, **Then** it uses `operations` rather than `runs` as the visible plural noun.
2. **Given** a platform or tenant health indicator refers to recent operation history, **When** it renders, **Then** the summary reinforces the same `Operations / Operation` vocabulary used by links and details.

### Edge Cases

- Workflow verbs that describe starting new work, such as `Start verification`, remain valid when they describe the task being initiated rather than an already-created `OperationRun` record.
- Existing internal route slugs, PHP class names, enum values, and table names may continue to use `run` terminology; this slice only governs operator-visible language.
- Shared helper layers must not regress Spec 170 system-surface naming while this slice updates non-system surfaces.
- A surface may link to either workspace/admin or platform detail, but the visible noun must still describe the destination record as an `Operation`.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new execution path, no new outbound work, and no new long-running process. It only standardizes visible operator-facing language for existing `OperationRun` references.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature adds no new structure, persistence, abstraction, or state family. It reduces naming drift in the existing presentation layer.

**Constitution alignment (UI-NAMING-001):** Operator-visible references to `OperationRun` records outside Spec 170 MUST resolve to the canonical visible nouns `Operations` and `Operation`, while internal implementation names may remain stable.

**Constitution alignment (OPSURF-001):** Shared links, embedded reports, and summary widgets must describe existing operation records with the same vocabulary as the canonical destinations they open.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-REVIEW-001):** This slice does not introduce new operator surfaces, but it must keep primary navigation labels, identifiers, and summary nouns consistent across existing surfaces so operators do not learn multiple names for the same domain object.

**Constitution alignment (UI-FIL-001):** Existing Filament actions, widgets, notifications, and embedded components remain the delivery mechanism. No new local UI framework or styling system is introduced.

**Constitution alignment (TEST-TRUTH-001):** Representative coverage must assert visible operator language on shared links and representative components so naming regressions fail in CI instead of relying on manual review.

### Functional Requirements

- **FR-171-001**: Operator-visible references to existing `OperationRun` records outside Spec 170 MUST use `Operations` as the canonical visible collection noun and `Operation` as the canonical visible singular noun.
- **FR-171-002**: Operator-visible navigation actions that open a specific existing operation record MUST use `Open operation` or a panel-appropriate equivalent rather than `View run`.
- **FR-171-003**: Operator-visible identifier labels for existing operation records MUST use `Operation #<id>` and `Operation ID` rather than `Run #<id>` and `Run ID`.
- **FR-171-004**: Verification and onboarding surfaces MAY keep workflow verbs such as `Start verification`, but any visible link, identifier, or helper copy that refers to the resulting historical record MUST use `operation` terminology rather than `run` terminology.
- **FR-171-005**: Summary or helper copy that refers to multiple existing `OperationRun` records MUST use `operations` rather than `runs` when the subject is operation history, failures, or stuck work.
- **FR-171-006**: The implementation MUST update shared label-producing layers, including catalogs, resolvers, reference presenters, or notification builders, wherever those layers are the source of visible naming drift across multiple surfaces.
- **FR-171-007**: This feature MUST NOT rename internal PHP class names, route slugs, enum values, persistence artifacts, or operation type identifiers.
- **FR-171-008**: Existing route destinations, authorization checks, and operation lifecycle semantics MUST remain unchanged.
- **FR-171-009**: Representative automated coverage MUST verify that covered non-system operator surfaces no longer render `View run`, `Run ID`, or `Run #` when referring to an existing `OperationRun` record.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Shared related links and references | shared presenters, catalogs, and resolvers used across resources and widgets | n/a | explicit `Open operation` link when present | existing safe link only | n/a | n/a | n/a | n/a | no new audit behavior | Naming-only slice; no new action family |
| Tenantless/admin operation viewers | `app/Filament/Pages/Operations/TenantlessOperationRunViewer.php` and shared reference summaries | existing viewer actions remain | n/a | existing related links remain | n/a | n/a | existing header actions remain | n/a | no new audit behavior | Title, secondary labels, and related links use `Operation` |
| Verification and onboarding report surfaces | tenant widgets and onboarding report/modals under `resources/views/filament/**` and their backing widgets/pages | existing workflow actions remain | n/a | one existing safe operation link when present | n/a | existing workflow CTA remains on owning surface | n/a | n/a | no new audit behavior | Workflow verbs stay task-oriented; record links and IDs use `Operation` |
| Summary and health widgets | representative tenant/platform widgets that describe operation history | existing page/widget actions remain | n/a | single existing drill-in or passive summary | n/a | existing surface-specific CTA behavior remains | n/a | n/a | no new audit behavior | Summary nouns use `operations` rather than `runs` |

### Key Entities *(include if feature involves data)*

- **Shared operation label source**: Existing catalogs, resolvers, presenters, or notifications that emit operator-facing operation labels.
- **Embedded operation report surface**: Existing widget, modal, or Blade component that exposes one operation record inside a broader workflow.
- **Operation summary copy**: Existing pluralized helper or status text that describes multiple `OperationRun` records.

## Success Criteria *(mandatory)*

- **SC-171-001**: Representative automated coverage verifies that shared operation links on covered non-system surfaces use `Operation` terminology rather than `run` terminology.
- **SC-171-002**: Representative automated coverage verifies that covered verification/onboarding surfaces use `Operation ID` or `Operation #<id>` rather than `Run ID` or `Run #<id>` for existing operation records.
- **SC-171-003**: Representative automated coverage verifies that covered summary widgets use plural `operations` wording rather than plural `runs` wording when referring to existing `OperationRun` records.
- **SC-171-004**: The feature ships without adding any new route, capability, persistence artifact, or internal rename requirement.

## Assumptions

- Spec 170 already owns visible Operations / Operation naming for the system-panel operations surfaces.
- Panel-appropriate detail routes remain the correct canonical destinations for existing operation records.
- Not every use of the English verb `run` is wrong; this slice only governs operator-visible references to `OperationRun` records.

## Non-Goals

- Renaming PHP classes, routes, tables, or enum values that contain `run`
- Reworking the action-surface behavior of deferred dashboard or onboarding surfaces beyond visible naming alignment
- Changing operation lifecycle semantics, queued-run feedback, or notifications beyond their visible labels
- Revisiting operation type taxonomy, `OperationCatalog` strategy, or provider-domain naming beyond the visible operator copy needed for this slice

## Dependencies

- Spec 170 system-surface naming alignment
- Existing operation detail routes in admin and system panels
- Existing shared label catalogs, related-navigation resolvers, reference presenters, notifications, widgets, and verification report components

## Definition of Done

Spec 171 is complete when representative non-system operator surfaces that refer to existing `OperationRun` records use `Operations / Operation` as the canonical visible noun family, shared deep-link labels and identifiers no longer say `View run`, `Run ID`, or `Run #`, verification surfaces keep task verbs distinct from record nouns, and automated coverage protects the updated naming without requiring route or persistence refactors.