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)

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)

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.