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

# Implementation Plan: Tenant Dashboard Operations Curation & Decision-First UX

**Branch**: `273-tenant-dashboard-active-operations-summary-card` | **Date**: 2026-05-07 | **Spec**: [spec.md](./spec.md)

## Summary

This scope refresh narrows the Tenant Dashboard back to decision-first operations UX. The dashboard keeps one attention KPI, one attention-only recommended action, and one compact `Operations requiring attention` card. It stops rendering recent operations history on the dashboard and pushes detail/history back to the canonical Operations Hub.

## Implementation Shape

- Keep all logic inside the existing `TenantDashboardSummaryBuilder` + `TenantDashboardOverview` path.
- Reuse `OperationRun::dashboardNeedsFollowUp()`, `OperationRunLinks`, and `OperationUxPresenter`.
- Reuse canonical Operations Hub filters by dominant real problem class.
- Remove the recent-operations overview section from the tenant dashboard Blade.
- Keep Filament v5 + Livewire v4, no provider-registration changes, no new panels/resources/assets.

## Affected Surfaces

- `apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php`
- `apps/platform/resources/views/filament/widgets/dashboard/tenant-dashboard-overview.blade.php`
- `apps/platform/lang/en/localization.php`
- `apps/platform/lang/de/localization.php`
- `apps/platform/tests/Feature/Dashboard/TenantDashboardProductizationSummaryTest.php`
- `apps/platform/tests/Feature/Dashboard/TenantDashboardProductizationActionsTest.php`
- `apps/platform/tests/Feature/Filament/TenantDashboardDbOnlyTest.php`
- `apps/platform/tests/Browser/Dashboard/TenantDashboardProductizationSmokeTest.php`

## Design Decisions

### Query contract

- Centralize dashboard attention logic in one tenant/workspace-scoped attention query.
- Attention means only `dashboardNeedsFollowUp()` runs.
- Healthy active runs are excluded from the dashboard decision card.

### KPI contract

- Keep the KPI slot and chart.
- Replace history-window wording with attention-only decision copy.
- KPI click remains a canonical Operations Hub drill-through.

### Recommended action contract

- Promote operations attention above informative readiness states.
- Keep it below missing permissions and high severity findings.
- Use exact review-oriented copy from the scope refresh.

### Card contract

- Show at most three attention items.
- Per item: title, outcome sentence, reason, impact, time, `Review operation`.
- Card-level secondary CTA: `Open operations hub`.
- No recent-history list remains on the dashboard.

## RBAC / Isolation

- Tenant membership stays the first gate.
- All counts and items remain scoped by `managed_environment_id` and `workspace_id`.
- If the actor cannot access tenant operations, the dashboard card and links stay hidden.

## Validation

- Focused tests:
  - `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`
- Formatting:
  - `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`

## Guardrails

- Do not add a second operations inbox or history block to the dashboard.
- Do not invent dashboard-only filters or route strings.
- Do not expose raw diagnostics or payload details on the dashboard.
- Do not change provider registration, global search, or destructive-action behavior.

### Phase 1 - Add one derived active-operations summary payload

- Extend `TenantDashboardSummaryBuilder` with one compact summary payload that returns count, highlighted run, status/guidance, and canonical navigation actions.
- Reuse `ActiveRuns`, `OperationRun::dashboardNeedsFollowUp()`, `OperationUxPresenter`, and `OperationRunLinks` instead of inventing a new query or presenter layer.
- Keep ranking deterministic: follow-up-needed/stale first, healthy queued/running second, then recency.

### Phase 2 - Render the card inside the existing overview composition

- Add the compact card to `tenant-dashboard-overview.blade.php` inside the current main-column composition.
- Use current dashboard card language and Filament primitives, keep one dominant `View operation` action, and keep `Show all operations` neutral.
- Hide the card entirely when no qualifying visible signal exists.

### Phase 3 - Prove calmness, truth, and tenant-safe visibility

- Extend focused Feature coverage for visible, hidden, priority, and shared-link behavior.
- Extend or reuse the existing negative tenant dashboard feature proof for non-member or no-OperationRun-visibility suppression.
- Update the existing browser smoke so the real dashboard first screen proves the card appears only when warranted and does not regress the calm layout.

## Proportionality Review

- **Current operator problem**: the current Tenant Dashboard can show operations only as aggregate posture or recent history, which forces the operator to infer whether current tenant work needs attention right now.
- **Existing structure is insufficient because**: the `Active operations` KPI is aggregate-only, and `Recent operations` is history-oriented. Neither surface provides one truthful highlighted run plus a dominant next action.
- **Narrowest correct implementation**: one derived summary payload inside the current dashboard summary builder plus one compact card in the existing overview view.
- **Ownership cost created**: a small summary-builder extension, one dashboard render slice, and focused feature/browser proof that must stay aligned with shared OperationRun helpers.
- **Alternative intentionally rejected**: reusing the full shell banner or building a new Operations widget family was rejected because both would make the dashboard louder and broader than the governance-first contract requires.
- **Release truth**: current-release truth. The repo already ships the dashboard, KPI, recent-operation cards, and canonical Operations surfaces; this plan only fills the bounded missing summary seam.