TenantAtlas/specs/273-tenant-dashboard-active-operations-summary-card/spec.md

Feature Specification: Tenant Dashboard Operations Curation & Decision-First UX

Feature Branch: 273-tenant-dashboard-active-operations-summary-card
Created: 2026-05-07
Status: Ready for implementation
Input: repo-based scope refresh from the original active-operations-summary slice after product review identified dashboard drift: operations had become visible in too many places on the Tenant Dashboard and needed to be reduced to decision-only attention surfaces.

Spec Candidate Check

• Problem: the Tenant Dashboard currently exposes operation truth through too many surfaces at once: KPI, recommended action, attention card, and recent-history rendering. That pushes the dashboard toward a second Operations hub instead of a governance-first decision surface.
• User-visible improvement: the dashboard keeps only attention-relevant operations. Healthy active or recent historical runs stop taking space on the first screen, while stale or follow-up-needed runs stay visible with one clear next action.
• Smallest enterprise-capable version: keep the Active operations KPI as an attention KPI, add one review-oriented recommended action when operations need follow-up, render one compact Operations requiring attention card with at most 1-3 runs, and remove the recent-operations section from the dashboard overview.
• Explicit non-goals: no second operations console, no raw diagnostics on the dashboard, no new persistence, no new OperationRun lifecycle, no new panel/resource/search surface, no route-family changes, and no compatibility shims.
• Why now: repo truth already ships canonical Operations list/detail surfaces. The remaining gap is not more operations visibility, but curation: the dashboard must stop duplicating history/detail surfaces and only show decision-relevant execution truth.

Scope

• Primary route: /admin/t/{tenant} Tenant Dashboard
• Canonical drill-through routes:
  • /admin/operations
  • /admin/operations/{run}
• Source of truth: existing tenant-scoped operation_runs only
• RBAC: existing tenant membership and operation visibility remain authoritative. Non-members remain 404, and no card, count, or CTA may leak hidden runs.

Shared Pattern Reuse

• Cross-cutting feature: yes
• Interaction classes: dashboard KPI, recommended actions, decision card, canonical run navigation
• Shared contracts reused: OperationRunLinks, OperationUxPresenter, ActiveRuns, TenantDashboardSummaryBuilder
• Required consistency:
  • Dashboard remains decision-first
  • Operations Hub remains diagnostics/history-first
  • OperationRun remains execution truth
  • No local dashboard-only run lifecycle or fake filters

UX Contract

A. KPI Card

• Keep the existing Active operations KPI slot.
• Count only attention-relevant operations.
• Show one short decision sentence:
  • No operations need attention
  • 1 operation needs follow-up
  • :count operations require attention
• KPI click opens the canonical Operations Hub in current tenant context with the dominant real attention filter.

B. Recommended Next Actions

• Show a recommended action only when attention-relevant operations exist.
• Required copy:
  • Title: Review operations requiring attention
  • Reason: One or more operations finished with an outcome that needs follow-up.
  • Impact: The tenant should not be treated as fully healthy until the operation outcome has been reviewed.
  • Primary CTA: Review operations
• Priority rule:
  • lower than missing provider permissions
  • lower than high severity findings
  • higher than purely informative readiness/status items

C. Operations Requiring Attention Card

• Render only when at least one attention-relevant run exists.
• Card title: Operations requiring attention
• Show at most 1-3 operations.
• Per operation show:
  • clear title
  • human-readable outcome sentence
  • reason
  • impact
  • relative time
  • primary CTA: Review operation
• Card-level secondary CTA: Open operations hub
• Healthy queued/running work is excluded from this card.
• Recent-history rendering is not shown on the Tenant Dashboard.

Acceptance Criteria

1. The Tenant Dashboard does not render a Recent Operations section.
2. Healthy queued/running operations do not create a dashboard attention card.
3. Terminal follow-up and stale-active runs do create a dashboard attention signal.
4. The KPI uses attention-only decision copy, not history-window copy.
5. The recommended action appears only when attention-relevant operations exist and uses the required copy.
6. The attention card shows at most 1-3 operations and each operation has Review operation.
7. Open operations hub and KPI drill-through use canonical OperationRunLinks tenant-scoped URLs.
8. The dashboard exposes no raw diagnostics, no execution-history table, and no additional operations overview block.
9. Cross-tenant or hidden runs never affect dashboard counts, items, or links.

Test & Validation

• Test classification: Feature + Browser
• Validation commands:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Dashboard/TenantDashboardProductizationSummaryTest.php tests/Feature/Dashboard/TenantDashboardProductizationActionsTest.php tests/Feature/Filament/TenantDashboardDbOnlyTest.php tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent

Boundaries

• No Livewire v3 / Filament v3-v4 patterns. This remains Filament v5 + Livewire v4.
• No provider-registration changes; apps/platform/bootstrap/providers.php remains authoritative.
• No global-search impact.
• No destructive actions are introduced.
  • non-member / not entitled to workspace scope OR tenant scope -> 404 (deny-as-not-found)
  • member but missing capability -> 403
• describe how authorization is enforced server-side (Gates/Policies) for every mutation/operation-start/credential change,
• reference the canonical capability registry (no raw capability strings; no role-string checks in feature code),
• ensure global search is tenant-scoped and non-member-safe (no hints; inaccessible results treated as 404 semantics),
• ensure destructive-like actions require confirmation (->requiresConfirmation()),
• include at least one positive and one negative authorization test, and note any RBAC regression tests added/updated.

Constitution alignment (OPS-EX-AUTH-001): OIDC/SAML login handshakes may perform synchronous outbound HTTP (e.g., token exchange) on /auth/* endpoints without an OperationRun. This MUST NOT be used for Monitoring/Operations pages.

Constitution alignment (BADGE-001): If this feature changes status-like badges (status/outcome/severity/risk/availability/boolean), the spec MUST describe how badge semantics stay centralized (no ad-hoc mappings) and which tests cover any new/changed values.

Constitution alignment (UI-FIL-001): If this feature adds or changes Filament or Blade UI for admin/operator surfaces, the spec MUST describe:

• how the affected surface follows docs/ui/tenantpilot-enterprise-ui-standards.md,
• which native Filament components or shared UI primitives are used,
• whether any local replacement markup was avoided for badges, alerts, buttons, or status surfaces,
• how semantic emphasis is expressed through Filament props or central primitives rather than page-local color/border classes,
• how the feature avoids ad-hoc custom styling for cards, buttons, hovers, badges, icons, progress bars, empty states, and interactive rows,
• how any custom Blade, Livewire widget, page, or dashboard surface preserves Filament-native interaction semantics and avoids introducing an independent button, status-color, spacing, or card system,
• how each affected page or focused action area keeps at most one dominant primary action and keeps secondary actions neutral unless they are destructive or the semantic state change is the point of the action,
• how status is conveyed through BADGE-001 badges, labels, chips, or supporting text rather than arbitrary button colors or per-card custom action styling,
• how hover, pointer, focus, shadow, or similar interactive affordance is used only when a repo-real route/action and permitted capability exist, and how non-interactive rows remain visibly static,
• how any required local Blade/Tailwind cards still preserve dark mode correctness, spacing consistency, badge semantics, action hierarchy, progressive disclosure, accessibility, and Filament visual language, and are used to compose product-specific layout rather than a parallel local design system,
• and any exception where Filament or a shared primitive was insufficient, including why the exception is necessary and how it avoids introducing a new local status language.

Constitution alignment (UI-NAMING-001): If this feature adds or changes operator-facing buttons, header actions, run titles, notifications, audit prose, or related helper copy, the spec MUST describe:

• the target object,
• the operator verb,
• whether source/domain disambiguation is actually needed,
• how the same domain vocabulary is preserved across button labels, modal titles, run titles, notifications, and audit prose,
• and how implementation-first terms are kept out of primary operator-facing labels.

Constitution alignment (DECIDE-001): If this feature adds or changes operator-facing surfaces, the spec MUST describe:

• whether each affected surface is a Primary Decision Surface, Secondary Context Surface, or Tertiary Evidence / Diagnostics Surface, and why,
• which human-in-the-loop moment each primary surface supports,
• what MUST be visible immediately for the first decision,
• what is preserved but only revealed on demand,
• why any new primary surface cannot live inside an existing decision context,
• how navigation follows operator workflows rather than storage structures,
• how one governance case remains decidable in one focused context,
• how any new automation, notifications, or autonomous governance logic reduce search/review/click load,
• and how the resulting default experience is calmer and clearer rather than merely larger.

Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001): If this feature adds or changes an operator-facing surface, the spec MUST describe:

• the chosen broad action-surface class and why it is the correct classification,
• the chosen detailed surface type and why it is the correct refinement,
• the one most likely next operator action,
• the one and only primary inspect/open model,
• whether row click is required, allowed, or forbidden,
• whether explicit View or Inspect is present, and why it is present or forbidden,
• where pure navigation lives and why it is not competing with mutation,
• where secondary actions live,
• where destructive actions live,
• how grouped actions are ordered by meaning, frequency, and risk,
• the canonical collection route and canonical detail route,
• the scope signals shown to the operator and what real effect each one has,
• the canonical noun used across routes, labels, runs, notifications, and audit prose,
• which critical operational truth is visible by default,
• and any catalogued exception type, rationale, and dedicated test coverage.

Constitution alignment (ACTSURF-001 - action hierarchy): If this feature adds or materially changes header actions, row actions, bulk actions, or workbench controls, the spec MUST describe:

• how navigation, mutation, context signals, selection actions, and dangerous actions are separated,
• why any visible secondary action deserves primary-plane placement,
• why any ActionGroup is structured rather than a mixed catch-all,
• and why any workflow-hub, wizard, system, or other special-type exception is genuine rather than a convenience shortcut.

Constitution alignment (OPSURF-001): If this feature adds or materially refactors an operator-facing surface, the spec MUST describe:

• how the default-visible content stays operator-first on /admin and avoids raw implementation detail,
• which diagnostics are secondary and how they are explicitly revealed,
• how the dominant next action stays primary and how duplicate visible truth is avoided,
• which status dimensions are shown separately (execution outcome, data completeness, governance result, lifecycle/readiness) and why,
• how each mutating action communicates its mutation scope before execution (TenantPilot only, Microsoft tenant, or simulation only),
• how dangerous actions follow the safe-execution pattern (configuration, safety checks/simulation, preview, hard confirmation where required, execute),
• how workspace and tenant context remain explicit in navigation, action copy, and page semantics,
• and the page contract for each new or materially refactored operator-facing page.

Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001): If this feature adds UI semantics, presenters, explanation layers, status taxonomies, or other interpretation layers, the spec MUST describe:

• why direct mapping from canonical domain truth to UI is insufficient,
• which existing layer is replaced or why no existing layer can serve,
• how the feature avoids creating redundant truth across models, service results, presenters, summaries, wrappers, and persisted mirrors,
• and how tests focus on business consequences rather than thin indirection alone.

Constitution alignment (Filament Action Surfaces): If this feature adds or modifies any Filament Resource / RelationManager / Page, the spec MUST include a UI Action Matrix and explicitly state whether the Action Surface Contract is satisfied. The same section MUST state that each affected surface has exactly one primary inspect/open model, that redundant View actions are absent, that empty ActionGroup / BulkActionGroup placeholders are absent, and that destructive actions follow the required placement rules for the chosen surface type. If the contract is not satisfied, the spec MUST include an explicit exemption with rationale. The same section MUST also state whether UI-FIL-001 is satisfied and identify any approved exception.

Constitution alignment (UX-001 - Layout & Information Architecture): If this feature adds or modifies any Filament screen, the spec MUST describe compliance with UX-001: Create/Edit uses Main/Aside layout (3-col grid), all fields inside Sections/Cards (no naked inputs), View pages use Infolists (not disabled edit forms), status badges use BADGE-001, empty states have a specific title + explanation + exactly 1 CTA, and tables provide search/sort/filters for core dimensions. If UX-001 is not fully satisfied, the spec MUST include an explicit exemption with documented rationale.

Functional Requirements

• FR-001: The Tenant Dashboard MUST add only one compact active-operations summary surface inside the existing dashboard overview composition. It MUST NOT render the full Spec 268 shell activity banner on the dashboard by default.
• FR-002: Card eligibility, count, and highlighted-run truth MUST be derived from existing tenant-scoped OperationRun truth and shared helpers already used for activity or follow-up visibility. The dashboard MUST NOT invent a second lifecycle query model or dashboard-only status taxonomy.
• FR-003: When one or more qualifying visible runs are queued, running, stale, or otherwise still need follow-up in the current tenant, the dashboard MUST show one compact summary card that includes a count and one highlighted run.
• FR-004: Highlighted-run selection MUST prioritize follow-up-needed or stale attention over healthy queued or running work. When multiple runs share the same attention class, the highlighted run MUST fall back to a deterministic recency rule.
• FR-005: Default-visible card content MUST stay limited to concise count text, highlighted run label, one centralized status treatment, one short guidance line, and the canonical View operation and Show all operations navigation actions.
• FR-006: View operation MUST open the canonical detail route for the highlighted run through shared link helpers. Show all operations MUST open the canonical Operations collection in current tenant context through shared link helpers. Dashboard code MUST NOT hardcode raw route strings.
• FR-007: Failed, blocked, stale, or follow-up-needed work MUST receive stronger visual priority than healthy queued or running work. Healthy active work MUST remain a calm secondary signal rather than an alert banner.
• FR-008: When more than one qualifying run exists, the card MUST stay compact by showing one highlighted run plus the aggregate count and collection drill-through. It MUST NOT expand into a multi-row operations list, table, or dashboard-native inbox.
• FR-009: When no qualifying active or follow-up-needed runs are visible to the current actor, the active-operations summary card MUST remain hidden by default. Recently completed successful runs stay represented through Recent operations rather than keeping this card open.
• FR-010: The card MUST reuse the dashboard's existing polling cadence and current first-screen density constraints. It MUST NOT add a second poller, floating overlay, or full-width panel that competes with recommended actions, governance status, or readiness cards.
• FR-011: The card MUST complement rather than duplicate the existing Active operations KPI and Recent operations section. The KPI remains aggregate posture, Recent operations remains recent history, and the new card remains the current active-or-follow-up summary.
• FR-012: The surface MUST stay governance-first and decision-first: one dominant next action, diagnostics-secondary disclosure, no raw implementation detail, and no dashboard-local operations-console affordances.

Authorization and Safety Requirements

• AR-001: Existing tenant/admin-plane authorization semantics remain unchanged: non-members or out-of-scope tenant actors remain 404, while canonical Operations routes continue using current OperationRun authorization for in-scope actors.
• AR-002: The card's count, highlighted run, and both navigation actions MUST be limited to runs the current actor can already view through canonical Operations routes. If the actor cannot view OperationRuns for the current tenant, the card MUST stay hidden.
• AR-003: No mutating or destructive action is introduced. Both card actions are navigation-only and must not imply acknowledgement, retry, dismissal, or lifecycle mutation.

Non-Functional Requirements

• NFR-001: Filament remains v5 on Livewire v4. No panel-provider registration change is allowed, and bootstrap/providers.php remains authoritative.
• NFR-002: No new panel, globally searchable resource, or asset-registration strategy is introduced. filament:assets deployment behavior is unchanged.
• NFR-003: The card must use existing dashboard composition patterns and Filament-native primitives or current shared dashboard styles. It must not introduce a new local card, badge, button, or hover language outside the current dashboard family.
• NFR-004: Counted, phased, or composite progress semantics remain owned by Specs 270, 271, and 272. This feature may consume current shared status and guidance truth, but it must not invent progress meters, fake percentages, or dashboard-only phase language.
• NFR-005: The implementation must preserve current dark-mode correctness, responsive first-screen stability, and current dashboard interaction honesty. Non-interactive areas remain static, and navigation affordances appear only where real routes and permissions exist.

Deferred Follow-Ups / Explicit Non-Goals

• dashboard-native shell-banner redesign or any full-width activity banner on the Tenant Dashboard
• counted-progress dashboard treatment already owned by 270 and 271
• phase or composite progress treatment on the dashboard already owned by 272
• a dashboard-native operations inbox, table, or console
• workspace-level or cross-tenant active-operations summary surfaces
• raw diagnostics, logs, payloads, or support-only execution evidence on the dashboard
• broader manual-promotion candidates such as Governance Artifact Lifecycle & Retention v1 and Enterprise Access Boundary & Support Access Governance v1

Key Entities

• Active Operations Summary Card: a derived, non-persisted Tenant Dashboard card that summarizes current active or follow-up-needed OperationRun truth for the current tenant without becoming a second operations console.
• Highlighted Operation Summary: the single derived run preview inside the card that determines the dominant next action and keeps View operation truthful when multiple qualifying runs exist.
• Qualifying Dashboard Operation Signal: an existing tenant-scoped OperationRun that is still active, stale, or otherwise needs follow-up and therefore deserves compact dashboard visibility.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: Focused Feature proof shows the Tenant Dashboard rendering one compact active-operations summary card when at least one qualifying visible run exists, with one highlighted run plus canonical View operation and Show all operations actions.
• SC-002: Focused Feature proof shows stale or follow-up-needed work outranking healthy queued or running work whenever both are visible for the current tenant.
• SC-003: Focused Feature plus browser proof shows the dashboard remaining calm when no qualifying visible run exists: no summary card, no full shell banner, and no first-screen layout regression.
• SC-004: Focused negative visibility proof shows actors without OperationRun visibility receiving no card content, no count leak, and no operation drill-through hints on the dashboard.
• SC-005: Covered dashboard scenarios keep the existing Active operations KPI and Recent operations section present and non-contradictory, with no second OperationRun truth source introduced.

Candidate Selection Rationale

• Selected candidate: Tenant Dashboard Active Operations Summary Card
• Source locations:
  • docs/product/spec-candidates.md
  • apps/platform/app/Filament/Pages/TenantDashboard.php
  • apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php
  • apps/platform/resources/views/filament/widgets/dashboard/tenant-dashboard-overview.blade.php
  • apps/platform/app/Filament/Widgets/Dashboard/DashboardKpis.php
  • apps/platform/tests/Feature/Dashboard/TenantDashboardProductizationSummaryTest.php
  • apps/platform/tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php
• Why selected: the automatic next-best-prep queue is intentionally empty, Specs 268 through 272 already exist around OperationRun maturity, and repo exploration confirms the exact gap named by candidate 273: the Tenant Dashboard currently has recent-operation cards and an Active operations KPI but no dedicated active-only summary card.
• Why this is the smallest viable implementation slice: it adds one compact dashboard-native summary over existing shared OperationRun truth and canonical links, without reopening shell-banner scope, progress semantics, new persistence, or new widget infrastructure.
• Why close alternatives were deferred:
  • Specs 269 through 272 are already specced and therefore are not the next unspecced repo-ready prep target
  • Governance Artifact Lifecycle & Retention v1 and Enterprise Access Boundary & Support Access Governance v1 remain broader, less bounded manual-promotion items that require larger product decisions than this dashboard follow-up

Related-Spec Guardrail Check

• specs/268-operationrun-activity-feedback/: this feature reuses the same run truth family but must not transplant the full shell banner onto the Tenant Dashboard.
• specs/269-operationrun-terminal-outcome-feedback/: any follow-up-needed or stale prioritization on the dashboard must stay aligned with the shell's terminal-outcome honesty rather than inventing a dashboard-only urgency model.
• specs/270-operationrun-progress-contract/: the dashboard card must consume shared OperationRun truth and must not invent local progress heuristics or fake percentages.
• specs/271-counted-progress-rollout/: any richer progress meter remains out of scope here and must flow through the counted-progress contract if it is ever added later.
• specs/272-operationrun-phase-composite-progress/: phase/composite progress language remains deferred and must not be smuggled into the dashboard card before the shared progress contract owns it.

Assumptions

• The canonical Operations collection already supports current-tenant drill-through behavior without requiring a new route family for this feature.
• Existing OperationRun helpers are sufficient to support highlighted-run selection and canonical link generation without introducing a new shared presenter layer.
• For v1, the calmest interpretation of the candidate's hidden or calm empty state rule is to keep the card hidden when there is no qualifying visible signal.

Risks

• The card can become noisy or redundant if it duplicates the Active operations KPI or Recent operations instead of keeping one distinct current-summary role.
• A dashboard-local prioritization rule can drift from shared shell or Operations semantics if the implementation stops reusing current shared helpers.
• Permission or tenant-filter mistakes could leak run counts or run existence through the summary card even if the canonical Operations route remains protected.

Open Questions

• None blocking safe implementation. If layout pressure later proves that a persistent empty-state slot is necessary, that should remain a narrow presentation decision and must not widen this slice into a second dashboard operations surface.