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.