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

# Implementation Plan: Operations Naming Consolidation

**Branch**: `171-operations-naming-consolidation` | **Date**: 2026-03-30 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/171-operations-naming-consolidation/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/171-operations-naming-consolidation/spec.md`

**Note**: This template is filled in by the `/speckit.plan` command. See `.specify/scripts/` for helper scripts.

Consolidate non-system operator-visible references to existing `OperationRun` records so shared links, notifications, embedded verification/onboarding reports, tenantless admin viewers, and summary/helper copy consistently use `Operations` / `Operation` while preserving existing route targets, capability checks, and operation lifecycle behavior. The implementation stays narrow: no schema, route, capability, or internal class renames; only shared label emitters, representative Filament/Blade surfaces, and focused Pest/Browser coverage are updated.

## Technical Context

**Language/Version**: PHP 8.4, Laravel 12, Livewire v4, Filament v5, Tailwind CSS v4  
**Primary Dependencies**: `laravel/framework`, `filament/filament`, `livewire/livewire`, `pestphp/pest`  
**Storage**: PostgreSQL with existing `operation_runs`, notification payloads, workspace records, and tenant records; no schema changes  
**Testing**: Pest unit, feature, Livewire, and browser tests executed through Laravel Sail  
**Target Platform**: Laravel web application running in Sail locally and containerized Linux environments for staging/production
**Project Type**: Laravel monolith with admin and system Filament panels plus shared Blade partials  
**Performance Goals**: Preserve existing DB-only render paths and current route/navigation behavior; add no remote calls, no new queued work, and no broader query fan-out than the current eager-loaded surfaces  
**Constraints**: Spec 170 remains authoritative for `/system/ops/*` interaction semantics; no internal class, route, enum, or persistence renames; workflow verbs such as `Start verification` remain where they describe new work; authorization, notification timing, and `OperationRun` lifecycle behavior stay unchanged  
**Scale/Scope**: One naming-only slice spanning shared navigation/presentation helpers, representative admin/tenant/workspace/platform-embedded surfaces, and focused unit/feature/browser regression coverage

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- `PASS` Inventory-first / snapshots-second: the slice does not change inventory, snapshot, backup, or artifact truth.
- `PASS` Read/write separation: no new write path is introduced; existing queued/terminal notifications and viewer actions keep their current behavior and only change visible naming.
- `PASS` Graph contract path: no Microsoft Graph integration path is touched.
- `PASS` Deterministic capabilities: no capability registry or role mapping changes are introduced.
- `PASS` RBAC-UX plane separation: the feature reuses existing admin, tenant, workspace-context, and platform routes without widening access or changing 404/403 semantics.
- `PASS` Workspace and tenant isolation: shared links continue to resolve through the current scoped routes and existing membership/capability checks remain authoritative.
- `PASS` Destructive confirmation standard: no destructive action behavior changes; existing confirmation requirements remain unchanged.
- `PASS` Ops-UX 3-surface feedback: queued and terminal notifications remain the same surfaces; only visible action labels and helper copy change.
- `PASS` Ops lifecycle ownership and summary-count rules: no `OperationRun.status`, `OperationRun.outcome`, or `summary_counts` behavior changes are introduced.
- `PASS` Proportionality / bloat: the feature adds no persistence, abstraction, state family, or cross-domain taxonomy and instead reduces visible drift through existing helpers.
- `PASS` UI naming (`UI-NAMING-001`): this feature directly standardizes operator-facing `OperationRun` nomenclature outside Spec 170.
- `PASS` UI surface taxonomy and inspect model: no new surface type or competing inspect model is introduced; embedded reports and viewers retain their current interaction model.
- `PASS` Filament-native UI (`UI-FIL-001`): the slice stays inside existing Filament actions, widgets, pages, and shared Blade views with no new local UI framework.
- `PASS` Testing truth (`TEST-TRUTH-001`): the plan updates representative rendered-surface tests instead of introducing a blanket string-ban guard that would catch valid uses of `run`.

## Project Structure

### Documentation (this feature)

```text
specs/171-operations-naming-consolidation/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── operation-naming-surface-contract.yaml
└── tasks.md
```

### Source Code (repository root)

```text
app/
├── Filament/
│   ├── Pages/
│   │   ├── Operations/
│   │   │   └── TenantlessOperationRunViewer.php
│   │   └── Workspaces/
│   │       └── ManagedTenantOnboardingWizard.php
│   ├── Resources/
│   │   ├── BackupScheduleResource.php
│   │   ├── BackupSetResource.php
│   │   ├── EvidenceSnapshotResource.php
│   │   └── EvidenceSnapshotResource/
│   │       └── Pages/
│   │           └── ViewEvidenceSnapshot.php
│   └── Widgets/
│       └── Tenant/
│           └── TenantVerificationReport.php
├── Notifications/
│   ├── OperationRunCompleted.php
│   └── OperationRunQueued.php
└── Support/
    ├── Baselines/
    │   └── BaselineCompareSummaryAssessor.php
    ├── Navigation/
    │   ├── RelatedActionLabelCatalog.php
    │   └── RelatedNavigationResolver.php
    ├── OpsUx/
    │   └── OperationUxPresenter.php
    ├── References/
    │   ├── ReferenceTypeLabelCatalog.php
    │   └── Resolvers/
    │       └── OperationRunReferenceResolver.php
    ├── Workspaces/
    │   └── WorkspaceOverviewBuilder.php
    └── OperationRunLinks.php

resources/
└── views/
    └── filament/
        ├── components/
        │   └── verification-report-viewer.blade.php
        ├── forms/
        │   └── components/
        │       └── managed-tenant-onboarding-verification-report.blade.php
        ├── modals/
        │   └── onboarding-verification-technical-details.blade.php
        ├── pages/
        │   └── monitoring/
        │       └── operations.blade.php
        └── widgets/
            └── tenant/
                ├── recent-operations-summary.blade.php
                └── tenant-verification-report.blade.php

tests/
├── Browser/
│   └── OnboardingDraftRefreshTest.php
├── Feature/
│   ├── Filament/
│   │   ├── BackupSetResolvedReferencePresentationTest.php
│   │   └── BaselineCompareSummaryConsistencyTest.php
│   ├── Guards/
│   │   └── ActionSurfaceContractTest.php
│   ├── Monitoring/
│   │   └── OperationLifecycleAggregateVisibilityTest.php
│   ├── Operations/
│   │   └── TenantlessOperationRunViewerTest.php
│   └── OpsUx/
│       └── NotificationViewRunLinkTest.php
└── Unit/
    └── Support/
        ├── References/
        │   └── RelatedContextReferenceAdapterTest.php
        └── RelatedNavigationResolverTest.php
```

**Structure Decision**: This is a single Laravel application. The implementation stays inside existing shared support classes, existing Filament/Blade surfaces, and the existing Pest/Browser test suite. No new application layer or directory is needed.

**Focused test inventory (authoritative)**: The tree above is representative, not exhaustive. The additional focused coverage for this feature is `tests/Feature/Filament/TenantVerificationReportWidgetTest.php`, `tests/Feature/Onboarding/OnboardingVerificationTest.php`, `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php`, `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php`, `tests/Feature/Filament/WorkspaceOverviewContentTest.php`, `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, and the Spec 170/shared-helper regression guard `tests/Feature/System/Spec114/OpsTriageActionsTest.php`, `tests/Feature/System/Spec114/OpsFailuresViewTest.php`, and `tests/Feature/System/Spec114/OpsStuckViewTest.php`.

## Complexity Tracking

No constitution waiver is expected. This slice narrows existing visible language drift instead of adding structure.

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | Not applicable | Not applicable |

## Proportionality Review

- **Current operator problem**: outside the already-aligned system-panel surfaces from Spec 170, the same `OperationRun` record is still presented as `run`, `operation run`, and `operation` depending on the page, widget, notification, or embedded report, which makes historical records feel like different domain objects.
- **Existing structure is insufficient because**: shared label catalogs, navigation resolvers, reference presenters, notifications, and embedded report partials each emit their own visible copy, so one-off local fixes would leave cross-surface drift in place and invite regression.
- **Narrowest correct implementation**: update the existing shared label emitters first, then patch only the representative non-system surfaces that still render local `run` terminology, while leaving routes, classes, enums, and lifecycle behavior intact.
- **Ownership cost created**: low. The feature requires targeted wording updates and representative unit/feature/browser assertions for rendered copy, but adds no new runtime abstraction or persistence burden.
- **Alternative intentionally rejected**: renaming internal PHP classes, route slugs, or operation-type identifiers was rejected because the feature scope is operator-visible naming consistency, not internal refactoring.
- **Release truth**: current-release truth. The naming drift already exists across the shipped workspace, tenant, and embedded operation-related surfaces.

## Post-Design Constitution Re-check

- `PASS` `UI-NAMING-001`: the design centralizes canonical `Operations` / `Operation` nouns in shared emitters and applies them consistently to links, identifiers, and helper copy.
- `PASS` `UI-CONST-001` / `UI-SURF-001` / `UI-HARD-001`: no surface classification, inspect model, or action-hierarchy change is introduced; only operator-visible naming changes.
- `PASS` `OPSURF-001`: verification and onboarding surfaces keep workflow verbs for starting work while naming the resulting historical record as an operation.
- `PASS` `RBAC-UX-001` through `RBAC-UX-005`: existing route, visibility, and confirmation semantics remain unchanged because only labels and helper copy move.
- `PASS` `TEST-TRUTH-001`: design coverage focuses on rendered links, identifiers, and plural summary copy across unit, feature, and browser tests.
- `PASS` `BLOAT-001`: no new persistence, abstraction, state, or taxonomy was introduced during design.
- `PASS` Filament v5 / Livewire v4 guardrails: the plan touches existing Filament and Livewire-compatible components only; no provider registration or asset strategy changes are required.