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)

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)

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.