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.