TenantAtlas/specs/399-dashboard-inbox-table-contract/plan.md

# Implementation Plan: Spec 399 - Dashboard / Inbox / Table Contract Migration v1

**Branch**: `399-dashboard-inbox-table-contract` | **Date**: 2026-06-22 | **Spec**: `specs/399-dashboard-inbox-table-contract/spec.md`
**Input**: Feature specification from `/specs/399-dashboard-inbox-table-contract/spec.md`

## Summary

Migrate existing `/admin` dashboard, inbox, and table-heavy surfaces to the Product Surface Contract introduced by Spec 395. The implementation should reduce default-visible complexity on Environment Dashboard, Workspace Overview, Governance Inbox, Findings list/inbox surfaces, Operations Hub, and directly touched hot tables. It must demote technical proof links, cap or product-paginate tables, preserve existing RBAC/audit/OperationRun behavior, and avoid any new runtime Product Surface framework.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12.52, Filament 5.2.1, Livewire 4.1.4, Pest 4.3, Tailwind CSS 4.2 through existing assets only  
**Storage**: PostgreSQL via existing Laravel models; no schema change planned  
**Testing**: Pest Feature/Livewire/Filament tests and Pest Browser focused smoke  
**Validation Lanes**: confidence + browser; fast-feedback only for pure helper assertions if introduced  
**Target Platform**: Laravel Sail locally, Dokploy container deployments for staging/production  
**Project Type**: Laravel monolith in `apps/platform` with Filament admin panel at `/admin`  
**Performance Goals**: no new render-time remote calls; dashboard/inbox/table default views remain DB-only where currently DB-only  
**Constraints**: no migrations, no new persisted truth, no new Product Surface runtime framework, no completed-spec rewrites, no legacy compatibility shims  
**Scale/Scope**: existing operator-facing `/admin` dashboard/inbox/table surfaces and directly touched hot tables only

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed rendered operator-facing surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - Environment Dashboard: `apps/platform/app/Filament/Pages/EnvironmentDashboard.php`, `apps/platform/app/Filament/Widgets/Dashboard/EnvironmentDashboardOverview.php`, `apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php`, and related dashboard widgets if touched.
  - Workspace Overview: `apps/platform/app/Filament/Pages/WorkspaceOverview.php`, `apps/platform/app/Support/Workspaces/WorkspaceOverviewBuilder.php`, workspace widgets under `apps/platform/app/Filament/Widgets/Workspace/`.
  - Governance Inbox: `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php`, `apps/platform/resources/views/filament/pages/governance/governance-inbox.blade.php`.
  - Findings: `apps/platform/app/Filament/Resources/FindingResource.php`, `apps/platform/app/Filament/Resources/FindingResource/Pages/ListFindings.php`, `apps/platform/app/Filament/Pages/Findings/MyFindingsInbox.php`, `apps/platform/app/Filament/Pages/Findings/FindingsIntakeQueue.php` where selected.
  - Operations Hub: `apps/platform/app/Filament/Pages/Monitoring/Operations.php`, `apps/platform/resources/views/filament/pages/monitoring/operations.blade.php`, and operation widgets if touched.
  - Touched hot tables in resources/pages/widgets named by implementation discovery.
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: mixed. Native Filament tables/actions should be used first; existing custom Blade/dashboard views may be reduced in place without inventing a parallel UI system.
- **Shared-family relevance**: dashboard signals, inbox lanes, Filament tables, action surfaces, OperationRun links, technical/audit links, badges/status messaging.
- **State layers in scope**: page, widget/builder payload, table state, row/bulk actions, URL-query filters where already present.
- **Audience modes in scope**: operator-MSP and manager by default; support-platform only for existing technical/detail paths; no new customer-facing default path.
- **Decision/diagnostic/raw hierarchy plan**: decision-first defaults, diagnostics second, raw/support technical proof hidden/collapsed/capability-gated.
- **Raw/support gating plan**: collapse or demote raw proof and technical detail; keep existing authorization.
- **One-primary-action / duplicate-truth control**: every touched page/section/item gets one primary action or triage path; repeated readiness/status summaries are removed or demoted.
- **Handling modes by drift class or surface**:
  - Product-facing dashboard/inbox/table overload: review-mandatory and fix in feature.
  - Existing completed-spec behavior outside touched files: report-only/context.
  - Product Surface budget exception: exception-required before runtime edit continues.
  - New runtime framework/status family/persistence need: hard-stop-candidate.
- **Repository-signal treatment**: default `document-in-feature`; escalate to `follow-up-spec` only for recurring table/action framework gaps outside the selected slice.
- **Special surface test profiles**: `standard-native-filament` for native tables, `monitoring-state-page` for Operations Hub, `global-context-shell` where Workspace Overview/Governance Inbox filters or shell state are affected.
- **List-surface review checklist**: `docs/product/standards/list-surface-review-checklist.md` must be reviewed before table/list edits and its result recorded in the implementation report.
- **Required tests or manual smoke**: Feature/Livewire table and action tests, focused browser smoke, Human Product Sanity.
- **Exception path and spread control**: no exceptions planned. Any exception must name the page/table, violated Product Surface rule, reason, why it remains safe, and follow-up if temporary.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **UI/Productization coverage decision**: update coverage artifacts for each rendered surface whose default UI changes.
- **Coverage artifacts to update**: `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`; page reports only when route/archetype/coverage classification materially changes.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: no panel provider or navigation restructure planned. If navigation links to target surfaces change visibility/prominence, record coverage artifact updates first.
- **Screenshot or page-report need**: focused browser screenshots/proof required for changed rendered surfaces; full page reports are proportional only when the existing registry becomes inaccurate.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
- **No-legacy posture**: canonical replacement. Do not preserve old overloaded layouts, labels, default row counts, proof links, or fixtures.
- **Page archetype and surface budget plan**:
  - Environment Dashboard: Dashboard Page, planned pass.
  - Workspace Overview: Dashboard Page, planned pass.
  - Governance Inbox: Inbox Page, planned pass.
  - Findings list/inbox: Inbox Page or Search/Index Page by exact host, planned pass.
  - Operations Hub: Inbox Page with technical details demoted, planned pass.
  - Touched hot tables: inherit host archetype and must satisfy table caps/action budgets unless documented exception.
- **Technical Annex and deep-link demotion plan**: demote OperationRun, raw evidence, source keys, detectors, fingerprints, UUIDs, payloads, provider payloads, raw report artifacts, restore proof, and technical logs from default product hierarchy.
- **Canonical status vocabulary plan**: map top-level product statuses to `Ready`, `Needs attention`, `Blocked`, `Running`, `Failed`, `Expired`, `Not configured`, `Unknown`, `Historical`, `Superseded`; use allowed severities only.
- **Product Surface exceptions**: none planned.
- **Browser verification plan**: focused Spec 399 browser smoke over Environment Dashboard, Workspace Overview, Governance Inbox, Findings, Operations Hub, and at least one directly touched hot table.
- **Human Product Sanity plan**: 5 to 15 minute review of changed surfaces, recorded in implementation report.
- **Visible complexity outcome target**: decreased. Neutral is allowed only when implementation proves a larger removal on the same surface.
- **Implementation report target**: `specs/399-dashboard-inbox-table-contract/implementation-report.md` during implementation.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire 4.1.4 confirmed by Laravel Boost application info. No Livewire v3 APIs may be introduced.
- **Panel provider registration location**: no panel provider changes planned; Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Global search posture**: no global search changes planned. If a touched Resource's global search behavior is changed, implementation must update spec/plan first and ensure a safe View/Edit page plus `$recordTitleAttribute`, or keep global search disabled.
- **Destructive/high-impact action posture**: no new destructive/high-impact actions planned. Any touched existing destructive or high-impact action must use `Action::make(...)->action(...)`, `->requiresConfirmation()`, server-side policy/gate authorization, audit logging where mutating, notification/error feedback, and Pest coverage.
- **Asset strategy**: no new Filament assets planned. Use existing CSS/Blade/Filament primitives. `filament:assets` is not required unless implementation registers new assets, which is not expected.
- **Testing plan**:
  - Feature/Livewire tests for row caps, table pagination/caps, default-hidden technical links, one primary action, and action grouping.
  - Existing surface tests updated where they assert old overloaded defaults.
  - Browser smoke over touched dashboard/inbox/table surfaces.
  - Browser or implementation-report proof for dark mode correctness, accessibility affordances, and Filament-native/shared-primitive semantics on touched custom Blade surfaces.
  - RBAC/authorization tests for any touched mutating or dangerous action.
- **Deployment impact**: no env vars, migrations, queues, scheduler, storage, or assets expected.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: Product Surface Contract, Filament Table UX Standard, action-surface declarations, dashboard widgets/builders, inbox page/lane builders, OperationRun link/presenter helpers, badge/status helpers, UI audit coverage artifacts.
- **Shared abstractions reused**: `TablePaginationProfiles`, `ActionSurfaceDeclaration` and related action-surface guard patterns, `BadgeCatalog` / `BadgeRenderer`, `UiEnforcement`, `WorkspaceUiEnforcement`, `OperationRunLinks`, `OperationUxPresenter`, existing surface builders/presenters.
- **New abstraction introduced? why?**: none planned. Small local helpers are allowed only when they reduce duplication inside a touched surface and do not become a cross-domain runtime framework.
- **Why the existing abstraction was sufficient or insufficient**: existing contracts already define budgets, status vocabulary, table profiles, and action/RBAC patterns. The implementation problem is default-visible hierarchy and table/link/action demotion, not missing platform truth.
- **Bounded deviation / spread control**: any page-local collapse/cap/helper must stay in the touched surface or existing domain builder and be documented in the implementation report.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes, by demoting default OperationRun proof links and preserving existing operation start/completion behavior.
- **Central contract reused**: `OperationRunLinks`, `OperationUxPresenter`, `OpsUxBrowserEvents`, `OperationRunService`, and the existing OperationRun lifecycle/notification path.
- **Delegated UX behaviors**: queued toast, operation link, artifact link, run-enqueued browser event, dedupe/blocked/start-failure messaging, and tenant/workspace-safe URL resolution remain delegated to existing helpers.
- **Surface-owned behavior kept local**: only placement/hierarchy of operation links within dashboards/inboxes/tables.
- **Queued DB-notification policy**: unchanged; no new queued DB notification opt-in.
- **Terminal notification path**: unchanged through central lifecycle.
- **Exception path**: none planned.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no.
- **Provider-owned seams**: existing provider-readiness/provider-connection display may be demoted if already on a touched surface, but provider credentials, Graph contracts, provider capability registry, and provider identity seams are not changed.
- **Platform-core seams**: Product Surface vocabulary and operator UI labels only.
- **Neutral platform terms / contracts preserved**: provider, environment, operation, evidence, finding, workspace.
- **Retained provider-specific semantics and why**: Microsoft/Intune details remain only where already repo-real and required in technical/detail paths.
- **Bounded extraction or follow-up path**: none planned.

## Constitution Check

*GATE: Must pass before implementation. Re-check after implementation discovery and before runtime UI edits if scope changes.*

- Inventory-first: pass; no Inventory truth changes.
- Read/write separation: pass; no new writes. Existing writes/dangerous actions must keep preview/confirmation/audit/tests.
- Graph contract path: pass; no Graph calls or contract changes.
- Deterministic capabilities: pass; existing capability checks remain authoritative.
- RBAC-UX: pass; UI visibility is not security, non-member 404 and member missing capability 403 semantics must remain intact.
- Workspace isolation: pass; workspace route/filter ownership remains explicit.
- Tenant isolation / managed-environment entitlement: pass; no cross-tenant aggregation changes.
- Run observability: pass; no new OperationRun types or lifecycle paths.
- OperationRun start UX: pass if existing helpers are reused; any local OperationRun UX composition is a blocker.
- Ops-UX 3-surface feedback: pass; unchanged.
- OperationRun lifecycle and summary counts: pass; no status/outcome/summary-count mutation planned.
- Data minimization: pass; technical proof is demoted rather than expanded.
- Test governance: pass with explicit confidence + browser lanes.
- Proportionality: pass; no new persistence, abstraction, status family, taxonomy, or UI framework approved.
- Shared pattern first: pass if existing table/action/badge/OperationRun helpers are reused.
- Provider boundary: pass; no provider seam changes.
- UI semantics / one truth few layers: pass; display maps existing truth directly to Product Surface vocabulary.
- Product Surface Contract Gate: pass planned; active spec/plan/tasks name surfaces, budgets, browser proof, human sanity, no-legacy posture, and implementation-report fields.
- Filament-native UI: pass planned; use native Filament components/shared primitives first and keep custom Blade inside existing surface conventions.
- Action-surface discipline: pass planned; one inspect/open model, grouped destructive/bulk actions, no empty groups.
- UI/Productization coverage: pass planned; route inventory and design matrix updates required for changed rendered surfaces.

## Test Governance Check

- **Test purpose / classification by changed surface**:
  - Environment Dashboard and Workspace Overview: Feature/Livewire + Browser.
  - Governance Inbox: Feature + Browser.
  - Findings table/inbox: Feature/Livewire table/action tests + Browser for selected host.
  - Operations Hub: Feature + Browser under `monitoring-state-page`.
  - Touched native tables: Feature/Livewire, browser only via changed host page.
- **Affected validation lanes**: confidence and browser.
- **Why this lane mix is the narrowest sufficient proof**: contract behavior is rendered UI plus table/action state; Feature tests prove data/action/link shape, Browser smoke proves first-viewport hierarchy and absence of runtime/console/Filament errors.
- **Narrowest proving commands**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec399`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec399DashboardInboxTableContractMigrationSmokeTest.php`
  - targeted existing Feature/Browser tests selected by implementation discovery
  - `cd apps/platform && ./vendor/bin/sail pint --dirty`
  - `git diff --check`
- **Fixture / helper / factory / seed / context cost risks**: keep reuse of existing surface fixtures explicit; do not widen default factories or browser setup.
- **Expensive defaults or shared helper growth introduced?**: no planned.
- **Heavy-family additions, promotions, or visibility changes**: one explicit focused browser smoke; no broad browser audit.
- **Surface-class relief / special coverage rule**: `standard-native-filament` relief for ordinary table cap tests; dashboard/inbox/Operations still require browser.
- **Closing validation and reviewer handoff**: implementation report must state commands, results, browser proof, unrelated failures, Product Surface exceptions, Human Product Sanity, visible complexity outcome, and no completed-spec rewrite assertion.
- **Budget / baseline / trend follow-up**: none expected; document-in-feature if browser fixture cost grows.
- **Review-stop questions**: lane fit, breadth, hidden fixture cost, heavy-family risk, Product Surface exception status.
- **Escalation path**: document-in-feature for contained exceptions; follow-up-spec only for structural table/action framework gaps.
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
- **Why no dedicated follow-up spec is needed**: this spec already owns the current dashboard/inbox/table Product Surface migration. Follow-up is only for secondary tables outside the touched slice.

## Project Structure

### Documentation (this feature)

```text
specs/399-dashboard-inbox-table-contract/
├── checklists/
│   └── requirements.md
├── plan.md
├── spec.md
└── tasks.md
```

No data model, contracts, or quickstart are required for preparation because this feature introduces no API, persisted entity, external contract, or new runtime data model.

### Source Code (repository root)

Likely implementation surfaces, subject to implementation discovery:

```text
apps/platform/app/Filament/Pages/
├── EnvironmentDashboard.php
├── WorkspaceOverview.php
├── Governance/GovernanceInbox.php
├── Findings/MyFindingsInbox.php
├── Findings/FindingsIntakeQueue.php
└── Monitoring/Operations.php

apps/platform/app/Filament/Widgets/
├── Dashboard/EnvironmentDashboardOverview.php
├── Dashboard/RecentOperations.php
└── Workspace/...

apps/platform/app/Filament/Resources/
├── FindingResource.php
├── FindingResource/Pages/ListFindings.php
└── OperationRunResource.php

Secondary/deferred table candidates, not default implementation surfaces unless T014 records a direct narrow touch:

apps/platform/app/Filament/Resources/
├── InventoryItemResource.php
├── PolicyResource.php
├── PolicyVersionResource.php
├── ProviderConnectionResource.php
├── BackupSetResource.php
├── RestoreRunResource.php
└── StoredReportResource.php

apps/platform/resources/views/filament/
├── widgets/dashboard/environment-dashboard-overview.blade.php
├── pages/governance/governance-inbox.blade.php
└── pages/monitoring/operations.blade.php

apps/platform/tests/Feature/
apps/platform/tests/Browser/

docs/ui-ux-enterprise-audit/
├── route-inventory.md
└── design-coverage-matrix.md
```

**Structure Decision**: Use existing Laravel/Filament page, widget, resource, view, and test directories only. Do not create new base folders or runtime frameworks.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None planned | N/A | N/A |

## Proportionality Review

- **Current operator problem**: dashboard, inbox, and table-heavy pages expose internal technical detail and too many actions/links/rows by default, making the next action harder to see.
- **Existing structure is insufficient because**: the existing Product Surface Contract exists, but the selected runtime surfaces still need migration to its budgets and technical demotion rules.
- **Narrowest correct implementation**: reduce existing surfaces and tests in place using native Filament/shared primitives first.
- **Ownership cost created**: focused Feature/Browser tests and implementation-report evidence only.
- **Alternative intentionally rejected**: Product Surface runtime framework, presenter/status family, persisted surface taxonomy, broad redesign, or compatibility mode.
- **Release truth**: current-release productization cleanup.

## Implementation Phases

### Phase 0 - Discovery and target lock

- Re-read active spec, plan, `docs/product/standards/product-surface-contract.md`, `docs/product/standards/filament-table-ux.md`, `docs/ui/action-surface-contract.md`, `docs/ui/operator-ux-surface-standards.md`, `docs/filament-guidelines.md`, and relevant existing specs.
- Inspect target files and tests to decide the exact first implementation slice.
- Record selected surfaces, untouched/deferred surfaces, and Product Surface exceptions before runtime UI edits.

### Phase 1 - Table budget and action contract foundation

- Identify every table/list section touched by the selected surfaces.
- Apply native Filament pagination/caps, product labels, hidden technical columns, one inspect/open model, and grouped destructive/bulk actions.
- Add or update Feature/Livewire tests before or alongside implementation.

### Phase 2 - Dashboard default reduction

- Reduce Environment Dashboard and Workspace Overview default content to one primary question, compact summary, top attention items, one next action, and demoted proof/detail links.
- Preserve existing authorized secondary/detail paths.
- Update Feature tests and focused browser expectations.

### Phase 3 - Inbox and Findings triage reduction

- Reduce Governance Inbox and selected Findings surfaces to prioritized work items, product row labels, severity/state/scope, and one next action.
- Demote source/evidence/OperationRun proof links.
- Update lane/list tests and browser smoke.

### Phase 4 - Operations Hub classification and technical demotion

- Keep Operations Hub as attention-oriented Inbox behavior with technical details demoted.
- Preserve OperationRun detail/technical paths for authorized users.
- Ensure operation status/progress/outcome semantics remain existing truth and no new OperationRun UX is composed locally.

### Phase 5 - Coverage artifacts, browser proof, and close-out

- Update `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md` for changed rendered surfaces.
- Run focused tests/browser smoke, Pint, and diff checks.
- Complete implementation report with Product Surface fields, no completed-spec rewrite assertion, Human Product Sanity, visible complexity outcome, deployment impact, and unrelated failure triage.