TenantAtlas/specs/172-deferred-operator-surfaces-retrofit/plan.md

# Implementation Plan: Deferred Operator Surfaces Retrofit

**Branch**: `172-deferred-operator-surfaces-retrofit` | **Date**: 2026-03-31 | **Spec**: `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/172-deferred-operator-surfaces-retrofit/spec.md`
**Input**: Feature specification from `/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/172-deferred-operator-surfaces-retrofit/spec.md`

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

Retrofit the existing embedded operation-bearing surfaces on the tenant detail page and onboarding verification flow so each state exposes one clear primary action, keeps scope truthful before navigation, and preserves the current canonical `OperationRun` destinations. The implementation stays narrow: reuse the existing Filament widgets, Blade partials, route helpers, and page-level actions; do not add routes, persistence, capabilities, assets, or a new embedded-surface framework.

## 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`, `managed_tenant_onboarding_sessions`, tenant records, and workspace records; no schema changes  
**Testing**: Pest feature, Livewire, and browser-style UI coverage executed through Laravel Sail  
**Target Platform**: Laravel web application running in Sail locally and containerized Linux environments for staging and production
**Project Type**: Laravel monolith with admin, tenant, and system Filament panels plus shared Blade partials  
**Performance Goals**: Preserve current DB-only render paths for tenant detail widgets and onboarding verification reports; add no remote calls, no new queued work, no new polling cadence, and no broader query fan-out than the current run lookups  
**Constraints**: `/admin/operations` and `/admin/operations/{run}` remain the canonical inspect destinations; no new route family, capability, persistence artifact, or `OperationRun` lifecycle change is allowed; tenant detail widgets must not render equal-weight competing CTAs; advanced monitoring links stay secondary and access-aware; no provider-registration, global-search, or asset-pipeline change is in scope  
**Scale/Scope**: Two tenant-detail embedded widgets, one onboarding verification report surface plus technical-details modal, one baseline exemption/governance note, and a focused set of Pest/Livewire regression tests

## Constitution Check

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

- `PASS` Inventory-first / snapshots-second: the feature does not change inventory truth, snapshot truth, or backup behavior; it only reorders and relabels derived inspection affordances.
- `PASS` Read/write separation: no new write path or long-running workflow is introduced; existing verification-start actions remain the same and only embedded presentation around existing `OperationRun` records is retrofitted.
- `PASS` Graph contract path: no Microsoft Graph contract or outbound-call path is changed.
- `PASS` Deterministic capabilities: no capability registry, role mapping, or authorization primitive is introduced or modified.
- `PASS` RBAC-UX plane separation: tenant-detail surfaces may continue linking to canonical admin-plane operation viewers, but they must do so without widening access; non-members remain 404 and member-but-missing-capability remains 403 on the existing destinations.
- `PASS` Workspace and tenant isolation: no new tenantless shortcut is introduced; current workspace context, tenant membership, and canonical route guards remain authoritative.
- `PASS` Destructive confirmation standard: no destructive action is added or altered in this slice.
- `PASS` Run observability / Ops-UX lifecycle: the plan reuses existing `OperationRun` records and route helpers only; no status/outcome transition logic, summary-count semantics, notification timing, or run-creation rules are changed.
- `PASS` Proportionality / abstraction / persistence / state (`PROP-001`, `ABSTR-001`, `PERSIST-001`, `STATE-001`, `BLOAT-001`): the feature adds no persistence, abstraction, enum, reason family, or semantic framework and instead narrows drift on existing current-release surfaces.
- `PASS` UI taxonomy and inspect model (`UI-CONST-001`, `UI-SURF-001`, `UI-HARD-001`): the affected surfaces remain embedded widgets and guided-flow report surfaces; the work reduces competing affordances instead of introducing new surface types or inspect models.
- `PASS` Operator surface rules (`OPSURF-001`): default-visible content stays operator-first, while diagnostics and advanced monitoring links remain secondary and explicitly revealed.
- `PASS` UI naming and Filament-native UI (`UI-NAMING-001`, `UI-FIL-001`): the feature reuses existing Filament sections, buttons, widgets, and Blade views, and keeps canonical `Operations` / `Operation` nouns without inventing a local presentation layer.
- `PASS` Testing truth (`TEST-TRUTH-001`): the design will extend focused widget, onboarding, and guard tests rather than introducing a broad string-ban or framework-only conformance layer.
- `PASS` Filament v5 / Livewire v4 guardrails: all touched surfaces already run on Filament v5 and Livewire v4; panel provider registration remains unchanged in `bootstrap/providers.php`; no new globally searchable resource is introduced; no asset strategy changes are needed, so deployment requirements for `filament:assets` are unchanged.

## Project Structure

### Documentation (this feature)

```text
specs/172-deferred-operator-surfaces-retrofit/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── embedded-operation-surface-contract.yaml
└── tasks.md
```

### Source Code (repository root)

```text
app/
├── Filament/
│   ├── Pages/
│   │   └── Workspaces/
│   │       └── ManagedTenantOnboardingWizard.php
│   ├── Resources/
│   │   └── TenantResource/
│   │       └── Pages/
│   │           └── ViewTenant.php
│   └── Widgets/
│       └── Tenant/
│           ├── RecentOperationsSummary.php
│           └── TenantVerificationReport.php
├── Support/
│   ├── OperationRunLinks.php
│   └── Ui/
│       └── ActionSurface/
│           └── ActionSurfaceExemptions.php

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

tests/
└── Feature/
    ├── Filament/
    │   ├── RecentOperationsSummaryWidgetTest.php
    │   └── TenantVerificationReportWidgetTest.php
    ├── Guards/
    │   └── ActionSurfaceContractTest.php
    └── Onboarding/
        ├── OnboardingVerificationClustersTest.php
        ├── OnboardingVerificationTest.php
        └── OnboardingVerificationV1_5UxTest.php
```

**Structure Decision**: This is a single Laravel application. The implementation stays inside existing tenant-detail widgets, onboarding report views, shared route helpers, and guard tests. No new panel, route family, base directory, or abstraction layer is needed.

**Focused test inventory (authoritative)**: `tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php`, `tests/Feature/Filament/TenantVerificationReportWidgetTest.php`, `tests/Feature/Onboarding/OnboardingVerificationTest.php`, `tests/Feature/Onboarding/OnboardingVerificationClustersTest.php`, `tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php` are the core regression surfaces for this slice.

## Complexity Tracking

No constitution waiver is expected. This slice intentionally avoids new persistence, abstractions, and UI frameworks.

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

## Proportionality Review

- **Current operator problem**: tenant-detail widgets and onboarding verification surfaces currently expose operation drill-ins with ambiguous scope and competing inline calls to action, which makes it unclear whether the operator should inspect existing execution truth or start new work.
- **Existing structure is insufficient because**: the current behavior is split across Blade branches, widget view-data helpers, and broad deferred-surface exemptions, so one-off wording fixes would not reliably enforce CTA hierarchy or scope-truth across the covered surfaces.
- **Narrowest correct implementation**: retrofit the existing tenant-detail widgets and onboarding verification views in place, reuse the canonical admin operation routes, and rely on the existing tenant-detail header action and onboarding step controls for rerun/start flows instead of adding a new embedded-action framework.
- **Ownership cost created**: low. The feature adds a surface contract artifact plus a focused set of widget/onboarding/governance assertions, but no schema, queue, routing, or abstraction maintenance burden.
- **Alternative intentionally rejected**: creating tenant-scoped operations routes, inventing a widget-specific action-surface declaration framework, or redesigning the entire tenant dashboard/tenant detail experience was rejected because the current-release need is limited to a few embedded operation-bearing surfaces.
- **Release truth**: current-release truth. The covered surfaces already ship today and already expose operation affordances that need clearer hierarchy and scope semantics.

## Post-Design Constitution Re-check

- `PASS` `UI-CONST-001` / `UI-SURF-001` / `UI-HARD-001`: the design keeps embedded summaries and guided-flow reports in their existing surface classes and narrows each to one primary inline action model instead of adding a new inspect mechanism.
- `PASS` `OPSURF-001`: tenant-detail widgets answer what happened and where to inspect it next, while onboarding keeps workflow controls (`Start verification`, `Refresh`) separate from diagnostics-only operation links.
- `PASS` `RBAC-UX-001` through `RBAC-UX-005`: existing server-side authorization, 404 vs 403 semantics, and confirmation rules remain unchanged because the design only changes CTA hierarchy and visible scope cues.
- `PASS` `UI-NAMING-001`: canonical `Operations` / `Operation` nouns remain stable across tenant-detail and onboarding inspect affordances without introducing scope-first labels.
- `PASS` `TEST-TRUTH-001`: the design expands focused Pest/Livewire coverage for CTA count, explicit scope cues, and advanced-link visibility rather than codifying a new cross-widget framework.
- `PASS` `BLOAT-001`: no new persistence, abstraction, state family, taxonomy, or presenter layer was added during design.
- `PASS` Filament v5 / Livewire v4 implementation contract: the plan touches existing Filament v5 and Livewire v4 widgets/pages only; panel providers remain registered in `bootstrap/providers.php`; no globally searchable resource changes are introduced; no destructive actions are added or modified; no asset registration changes are needed, so the deployment `filament:assets` step is unaffected.
- `PASS` Testing plan: implementation coverage will target `RecentOperationsSummaryWidgetTest`, `TenantVerificationReportWidgetTest`, `OnboardingVerificationTest`, `OnboardingVerificationClustersTest`, `OnboardingVerificationV1_5UxTest`, and `ActionSurfaceContractTest`.