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

# Feature Specification: Deferred Operator Surfaces Retrofit

**Feature Branch**: `172-deferred-operator-surfaces-retrofit`  
**Created**: 2026-03-30  
**Status**: Draft  
**Input**: User description: "Deferred Operator Surfaces Retrofit"

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + tenant + canonical-view
- **Primary Routes**:
  - `/admin/t/{tenant}`
  - `/admin/operations`
  - `/admin/operations/{run}`
  - managed-tenant onboarding flow routes that expose verification operation reports
- **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 status, deep-link destinations, and verification history
  - Tenant dashboard widgets, onboarding report components, and related embedded operation affordances remain derived presentation layers only
- **RBAC**:
  - No new capability family is introduced
  - Existing tenant, workspace, and admin access rules remain authoritative for every destination that a retrofitted surface may open
  - Retrofitted surfaces must not imply broader scope than the operator can actually inspect

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard operation cards and widgets | Embedded status summary / drill-in surface | Explicit CTA to a tenant-scoped operations destination | forbidden | card footer or secondary widget action only | none | tenant-scoped operations destination in admin panel | panel-appropriate operation detail when singular | current tenant remains explicit before navigation | Operations / Operation | active or recent operation truth, tenant context, next destination | retrofit existing deferred surface |
| Tenant verification report widget | Embedded operator detail panel | One primary inspect CTA to the existing operation when present | forbidden | advanced admin/monitoring link only if justified and clearly secondary | none | panel-appropriate operations collection when needed | panel-appropriate operation detail route | tenant context and current verification state explicit | Operations / Operation | verification state, operation identity, recency | retrofit existing deferred surface |
| Managed-tenant onboarding verification report and technical-details surfaces | Guided workflow sub-surface | One primary inspect CTA to the existing operation when present, otherwise one workflow-next-step CTA | forbidden | low-emphasis advanced links only when justified | none | panel-appropriate operations collection when needed | panel-appropriate operation detail route | workspace, tenant, and verification context explicit | Operations / Operation | verification status, operation identity, stale-state explanation | retrofit existing deferred surface |

## 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 |
|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard operation cards and widgets | Tenant operator | Embedded status summary / drill-in surface | What is happening in this tenant, and where do I inspect it? | tenant-scoped count or recent activity, explicit destination scope, one clear CTA | raw operation payloads and extended traces stay on destination surfaces | recency, active-state, failure/stuck summary | none | tenant-scoped operations drill-in | none |
| Tenant verification report widget | Tenant operator | Embedded operator detail panel | What verification operation ran for this tenant, and how do I inspect it? | verification result, one primary operation link, operation identity, timestamp | raw provider diagnostics stay behind explicit reveal or destination detail | verification outcome, recency, stale-state | none | `Open operation` or current-step CTA | none |
| Managed-tenant onboarding verification report and technical details | Workspace operator running onboarding | Guided workflow sub-surface | What verification operation supports this onboarding step, and what should I do next? | workflow state, operation identity when present, one primary CTA, scope cue | low-level payloads, hashes, and verbose traces stay in diagnostics sections or canonical detail | workflow status, verification outcome, stale-state | none | `Open operation` or `Start verification` | 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**: Dashboard widgets, tenant verification widgets, and onboarding verification components still behave like deferred or exempt surfaces even though they expose meaningful operation drill-ins, which leaves CTA count, scope cues, and deep-link behavior underdefined compared with the now-aligned table and detail surfaces.
- **Existing structure is insufficient because**: Spec 169 intentionally left these embedded surfaces out of the table-centric action-surface enforcement path, so the repo still permits tenant-context leaks, competing links, and scope-ambiguous operation affordances on high-traffic summary surfaces.
- **Narrowest correct implementation**: Retrofit only the deferred non-table surfaces that already expose operation affordances, give them explicit operator contracts and representative coverage, and keep unrelated deferred pages out of scope.
- **Ownership cost**: Existing dashboard and onboarding tests will need to assert CTA count, destination scope, and advanced-link visibility, and the exemption baseline or equivalent governance notes must be narrowed for the retrofitted surfaces.
- **Alternative intentionally rejected**: Broadly enrolling every deferred dashboard, chooser, landing page, or page-class route into the main action-surface validator was rejected because this slice only needs to retrofit operation-bearing embedded surfaces, not redesign every deferred surface family.
- **Release truth**: Current-release truth. The tenant dashboard and onboarding verification flows already expose operation links today, and current audits show scope and affordance drift on those surfaces.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Tenant Dashboard Drill-Ins Preserve Tenant Context (Priority: P1)

As a tenant operator, I want dashboard operation cards and widgets to send me to a destination that clearly preserves my current tenant context, so that I am not silently dropped into a broader workspace-wide operations surface.

**Why this priority**: Tenant dashboard drill-ins are a frequent entry point and currently carry the clearest cross-scope surprise risk.

**Independent Test**: Can be fully tested by rendering the relevant tenant dashboard operation affordances and asserting that their visible destination semantics remain tenant-scoped and do not silently link to an unfiltered workspace-wide operations surface.

**Acceptance Scenarios**:

1. **Given** a tenant operator on the tenant dashboard, **When** the operator opens a dashboard operation drill-in, **Then** the destination preserves tenant context or makes the broader scope explicit before navigation.
2. **Given** a tenant dashboard widget summarizes recent or active operations, **When** it renders, **Then** it exposes at most one primary operations drill-in rather than multiple competing operation links.

---

### User Story 2 - Onboarding And Verification Surfaces Expose One Clear Operation Path (Priority: P1)

As a workspace or tenant operator, I want verification widgets, onboarding report blocks, and technical-detail overlays to show one clear primary action for the relevant operation record, so that I know exactly where to inspect execution truth without sorting through competing links.

**Why this priority**: These surfaces are currently exempt yet already act like operator-facing execution summaries.

**Independent Test**: Can be fully tested by rendering representative tenant verification and onboarding verification surfaces in empty, in-progress, and completed states and asserting that each state has one primary CTA aligned to the operator's next step.

**Acceptance Scenarios**:

1. **Given** a verification-backed operation exists, **When** the report surface renders, **Then** exactly one primary `Open operation` affordance is visible for that record.
2. **Given** no verification-backed operation exists yet, **When** the owning verification or onboarding surface renders, **Then** the operator sees one clear next-step CTA such as `Start verification` and no competing inline operation links.
3. **Given** an advanced monitoring destination is still useful for some operators, **When** it is shown, **Then** it is explicitly secondary and does not compete with the primary inspect path.

---

### User Story 3 - Retrofitted Deferred Surfaces Gain Explicit Governance (Priority: P2)

As a reviewer, I want the deferred surfaces that already expose operations to stop relying on blanket exemptions, so that future regressions in CTA count, scope signals, or deep-link behavior are caught automatically.

**Why this priority**: Without explicit governance, the retrofitted surfaces will remain drift-prone even after a one-time UX fix.

**Independent Test**: Can be fully tested by proving that representative tenant dashboard and onboarding verification surfaces are covered by dedicated tests or governance checks, while unrelated deferred surfaces remain explicit non-goals.

**Acceptance Scenarios**:

1. **Given** the retrofit is complete, **When** representative tests or governance checks run, **Then** tenant dashboard and onboarding verification operation affordances are covered explicitly rather than relying on a blanket deferred exemption.
2. **Given** unrelated deferred surfaces such as chooser pages or landing pages remain untouched, **When** the retrofit ships, **Then** they remain explicit non-goals rather than being swept in accidentally.

### Edge Cases

- A tenant verification surface may need to show no current operation, an in-progress operation, or a stale completed operation; each state still needs one primary next-step affordance.
- Some operators may have access to the tenant-local surface but not to an advanced admin monitoring destination; advanced links must respect destination access.
- A retrofitted surface may expose a collection drill-in or a single-operation drill-in depending on context, but the scope must remain explicit either way.
- Unrelated deferred surfaces such as `ChooseTenant`, `ChooseWorkspace`, `ManagedTenantsLanding`, and the Monitoring Alerts page-class route remain out of scope unless they later gain operation affordances that justify a dedicated spec.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new execution path, no new long-running work, and no new persistence. It only retrofits existing embedded operator surfaces that already summarize or link to `OperationRun` records.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** This feature adds no new structure, persistence, abstraction, or state family. It narrows an existing deferred UX gap on current-release surfaces.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / UI-HARD-001 / UI-REVIEW-001):** Even though these are embedded or guided-flow surfaces rather than table pages, they must still expose one clear primary inspect or next-step model, keep scope truthful, and avoid competing actions.

**Constitution alignment (OPSURF-001):** Dashboard and onboarding verification surfaces must be operator-first summary surfaces: the default-visible content should answer what happened, what scope it affected, and where the operator should go next without exposing low-level diagnostics by default.

**Constitution alignment (UI-FIL-001):** Existing Filament pages, widgets, and embedded components remain the implementation shape. No local mini-framework for embedded operation actions is introduced.

**Constitution alignment (UI-NAMING-001):** The retrofitted surfaces use the canonical visible nouns `Operations` and `Operation`, consistent with Specs 170 and 171.

**Constitution alignment (TEST-TRUTH-001):** Representative automated coverage must assert CTA count, scope cues, and visibility of advanced links on the retrofitted surfaces.

### Functional Requirements

- **FR-172-001**: Tenant dashboard operation-bearing widgets or cards MUST expose navigation that preserves tenant context or makes any broader scope explicit before the operator leaves the tenant dashboard.
- **FR-172-002**: Retrofitted embedded surfaces that reference one existing operation record MUST expose exactly one primary inspect affordance for that record.
- **FR-172-003**: Retrofitted embedded surfaces in a no-history or no-operation state MUST expose exactly one primary next-step CTA on the owning surface and MUST NOT render competing inline operation links.
- **FR-172-004**: Any retained advanced admin or monitoring destination link MUST be clearly secondary, explicitly labeled for its scope or audience, and visible only when the operator can access that destination.
- **FR-172-005**: Retrofitted tenant or workspace surfaces MUST keep tenant, workspace, or admin scope explicit in their visible copy or destination semantics before navigation occurs.
- **FR-172-006**: Governance artifacts, exemption handling, or dedicated tests MUST stop treating the retrofitted operation-bearing parts of `TenantDashboard` and `ManagedTenantOnboardingWizard` as fully out of scope.
- **FR-172-007**: Unrelated deferred surfaces that do not expose operation affordances today, including `ChooseTenant`, `ChooseWorkspace`, `ManagedTenantsLanding`, and the Monitoring Alerts page-class route, MUST remain explicit non-goals for this slice.
- **FR-172-008**: Existing operation destinations, authorization rules, and lifecycle semantics MUST remain unchanged.
- **FR-172-009**: Representative automated coverage MUST verify CTA count, scope-truthful navigation, and advanced-link visibility on the tenant dashboard and onboarding verification surfaces affected by this slice.
- **FR-172-010**: This feature MUST NOT introduce a new dashboard page, a new onboarding flow, or a new operations capability.

## 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Tenant dashboard operation cards/widgets | `app/Filament/Pages/TenantDashboard.php` and its operation-bearing widgets | existing dashboard/header actions remain | n/a | one explicit operations drill-in per card/widget maximum | n/a | existing surface-specific next-step CTA remains singular | n/a | n/a | no new audit behavior | Retrofit current deferred widget/card surfaces with scope-truthful operations drill-ins |
| Tenant verification report widget | tenant verification widget and embedded report view | existing widget actions remain | n/a | one primary `Open operation` link when a record exists | n/a | owning surface keeps one workflow CTA when no operation exists | n/a | n/a | no new audit behavior | Advanced admin/monitoring link may remain only as secondary |
| Managed-tenant onboarding verification report and technical details | `app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php` and related onboarding report/modal views | existing workflow actions remain | n/a | one primary `Open operation` link when a record exists | n/a | `Start verification` or equivalent next-step CTA remains singular when no operation exists | n/a | n/a | no new audit behavior | Guided-flow retrofit; no new page or route family |

### Key Entities *(include if feature involves data)*

- **Deferred operation-bearing embedded surface**: Existing dashboard card, widget, report block, or modal that is not a table page but still exposes operation truth or navigation.
- **Primary inspect affordance**: The one visible link or CTA that opens the canonical operation destination for the current embedded context.
- **Advanced destination link**: A clearly secondary operation-related link that exposes a broader monitoring destination only for operators who can access it.

## Success Criteria *(mandatory)*

- **SC-172-001**: Representative automated coverage verifies that tenant dashboard operation drill-ins preserve tenant context or make any broader scope explicit before navigation.
- **SC-172-002**: Representative automated coverage verifies that covered verification and onboarding surfaces expose exactly one primary CTA per state.
- **SC-172-003**: Representative automated coverage verifies that any retained advanced monitoring/admin link is secondary and access-aware.
- **SC-172-004**: The feature ships without adding a new dashboard page, onboarding flow, operations capability, or persistence artifact.

## Assumptions

- Specs 170 and 171 establish the canonical visible noun family `Operations / Operation` for aligned and residual naming surfaces.
- Existing admin operation list and detail destinations remain the correct canonical inspect targets for embedded tenant/workspace surfaces.
- Retrofitting embedded operation-bearing surfaces is sufficient for this slice; not every currently exempt page needs to be enrolled.

## Non-Goals

- Building a new workspace home or redesigning the tenant dashboard as a whole
- Reworking onboarding flow mechanics or verification execution semantics
- Enrolling chooser pages, `ManagedTenantsLanding`, or the Monitoring Alerts page-class route into this retrofit when they do not currently expose operation affordances that need the same treatment
- Introducing a broad action-surface framework for all widgets and embedded components beyond the explicit retrofits in this slice

## Dependencies

- Spec 169 deferred-surface exemption baseline
- Spec 170 system operations surface alignment
- Spec 171 operations naming consolidation
- Existing tenant dashboard widgets, verification report widgets, onboarding verification report components, and canonical admin operation destinations

## Definition of Done

Spec 172 is complete when the deferred non-table surfaces that already expose operations, especially tenant dashboard operation drill-ins and onboarding/verification report surfaces, provide one clear primary CTA per state, preserve or explicitly announce scope before navigation, keep any advanced monitoring/admin links secondary and access-aware, and are protected by explicit governance or representative tests instead of relying on a blanket deferred exemption.