TenantAtlas/specs/330-environment-dashboard-baseline-compare-productization/plan.md

Implementation Plan: Spec 330 - Environment Dashboard / Baseline Compare Productization

Branch: 330-environment-dashboard-baseline-compare-productization | Date: 2026-05-19 | Spec: specs/330-environment-dashboard-baseline-compare-productization/spec.md Input: User-provided Spec 330 and repo inspection.

Summary

Productize two existing environment-owned strategic surfaces into decision-first governance pages:

Is this environment ready, blocked, stale, or requiring review?
Which baseline drift requires action?

The implementation must keep current routes, source truth, RBAC, environment-owned scope, and OperationRun semantics. It must not add new backend readiness/drift/proof engines. Environment Dashboard should elevate status, reason, impact, proof, and one primary next action before technical detail. Baseline Compare should elevate assignment, compare trust, drift impact, evidence/proof, and one primary next action before findings detail, raw diff, or diagnostics.

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.0. Primary Dependencies: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Tailwind CSS 4.2.2. Storage: PostgreSQL; no schema change expected. Testing: Pest 4 Feature/Livewire/Browser tests. Validation Lanes: confidence and browser; targeted navigation/context guard filters. Target Platform: Laravel Sail locally; Dokploy/container deployment posture unchanged. Project Type: Laravel monolith under apps/platform. Performance Goals: DB-only page render; no Graph/provider API calls during render; no broad new query families. Constraints: No new persisted truth, migration, package, queue, scheduler, storage, env var, deployment asset, compatibility route, or legacy alias support. Scale/Scope: Two existing environment-owned Filament pages, existing widget/view structures, feature-local payload helpers if needed, focused tests, and browser smoke.

UI / Surface Guardrail Plan

• Guardrail scope: changed existing operator-facing strategic environment-owned surfaces.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces:
  • /admin/workspaces/{workspace}/environments/{environment}
  • /admin/workspaces/{workspace}/environments/{environment}/baseline-compare
  • 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
  • apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-context-chips.blade.php
  • apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
  • apps/platform/app/Filament/Pages/BaselineCompareLanding.php
  • apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php
• No-impact class, if applicable: N/A.
• Native vs custom classification summary: Native Filament Dashboard/Page/Widget plus existing Blade composition; no new UI framework.
• Shared-family relevance: dashboard signals, status messaging, action links, proof links, OperationRun links, baseline compare state, diagnostics disclosure.
• State layers in scope: route-owned environment, page payload, widget payload, Baseline Compare launch query state (baseline_profile_id, subject_key, nav), and existing session/context guard behavior.
• Audience modes in scope: operator-MSP, manager, governance operator, support reviewer where authorized.
• Decision/diagnostic/raw hierarchy plan: decision first, proof path visible, diagnostics collapsed, raw/support hidden or gated.
• Raw/support gating plan: collapsed by default and capability-gated through existing support diagnostics/raw capabilities where exposed.
• One-primary-action / duplicate-truth control: one dominant next action per page; secondary links/cards support the decision rather than repeat the same verdict.
• Handling modes by drift class or surface: review-mandatory for UI-002 and UI-061 strategic surfaces; document-in-feature for any UI coverage registry no-change decision.
• Repository-signal treatment: Spec 325 target images are direction only; runtime claims must be repo-verified, derived, unavailable, or deferred.
• Special surface test profiles: global-context-shell, monitoring-state-page, shared-detail-family.
• Required tests or manual smoke: Feature/Livewire tests for decision layout, false-green guard, RBAC/scope/disclosure plus Pest Browser smoke for explicit environment routes, no-baseline/action-needed/drift states, diagnostics collapsed, raw detail hidden, cross-workspace denial, and static tenant copy guard.
• Exception path and spread control: none expected. Any new dangerous action, schema, capability, backend proof source, or route family requires spec/plan/tasks update first.
• Active feature PR close-out entry: Guardrail / Exception / Smoke Coverage.
• UI/Productization coverage decision: active spec package carries productization proof. Update UI coverage registry only if route/archetype/coverage classification changes; otherwise document why UI-002/UI-061 plus Spec 325 artifacts are sufficient.
• Coverage artifacts to update: none expected unless implementation changes route/archetype state.
• Navigation / Filament provider-panel handling: no panel provider registration changes expected. Laravel 12 panel providers remain in apps/platform/bootstrap/providers.php.
• Screenshot or page-report need: screenshots required; full page report optional unless implementation materially changes coverage classification.

Shared Pattern & System Fit

• Cross-cutting feature marker: yes.
• Systems touched: Environment Dashboard page, dashboard widgets, dashboard summary builder, Baseline Compare Landing page/view, baseline stats/aggregate helpers, backup/recovery helpers, provider permission view models, OperationRun links, resource policies, UiEnforcement, and browser fixtures/tests.
• Shared abstractions reused: EnvironmentDashboardSummaryBuilder, EnvironmentDashboardSummary, BaselineCompareStats, TenantGovernanceAggregateResolver, OperationRunLinks, ManagedEnvironmentLinks, OperationUxPresenter, OpsUxBrowserEvents, BadgeRenderer, UiEnforcement, policies/capability resolvers.
• New abstraction introduced? why?: none. Page-local private helpers may be added only to reduce Blade complexity or duplicate payload calculation.
• Why the existing abstraction was sufficient or insufficient: Existing paths provide source truth, authorization, links, compare state, backup/recovery/readiness signals, and OperationRun proof. They do not fully enforce the first-read decision hierarchy and collapsed diagnostics disclosure.
• Bounded deviation / spread control: no public readiness/proof/disclosure framework; keep composition local to the two surfaces.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, through existing Baseline Compare start action and proof links. No new OperationRun type or lifecycle behavior.
• Central contract reused: OperationRunLinks, OperationUxPresenter, OpsUxBrowserEvents, existing OperationRunPolicy, existing operation detail routes, and BaselineCompareService::startCompare().
• Delegated UX behaviors: compare queued toast, run-enqueued browser event, open operation link, blocked/cannot-start messaging, and tenant/workspace-safe URLs stay on the existing Ops UX path.
• Surface-owned behavior kept local: display-only proof availability labels and next-action hierarchy.
• Queued DB-notification policy: unchanged / N/A.
• Terminal notification path: unchanged.
• Exception path: none.

Provider Boundary & Portability Fit

• Shared provider/platform boundary touched?: display-only provider readiness/permissions and static copy guard.
• Provider-owned seams: existing provider connection, Microsoft/Entra/Intune required permissions, provider tenant ID where source records require it.
• Platform-core seams: workspace, environment, readiness, proof, baseline, drift, evidence, operation, review, diagnostics.
• Neutral platform terms / contracts preserved: workspace, environment, provider, required permissions, operation proof, evidence, review, baseline, drift, diagnostics.
• Retained provider-specific semantics and why: Microsoft/Entra/Intune can remain at source/provider-boundary labels only.
• Bounded extraction or follow-up path: Provider Readiness Productization remains a separate follow-up spec.

Constitution Check

• Inventory-first, snapshots-second: Environment and compare surfaces derive from last-observed inventory, explicit snapshots, backups, evidence, reviews, and operations; no new source truth is created.
• Read/write separation by default: Pages remain read/decision-first. Existing compare start is the only high-impact operation start and already requires confirmation/authorization/OperationRun.
• Single Contract Path to Graph: No Graph/provider API calls may be added to page render.
• Deterministic Capabilities: Reuse existing Capabilities, CapabilityResolver, resource policies, UiEnforcement, and route authorization.
• RBAC-UX: UI visibility is not security. Server-side policies/gates remain authoritative for operations, evidence, review packs, backup/restore, provider permissions, and diagnostics.
• Workspace/environment isolation: Both pages require explicit route-bound environment. Non-member or mismatched workspace/environment access is 404.
• OperationRun UX: Existing compare start and operation links reuse shared OperationRun UX helpers; no local lifecycle/notification behavior.
• UI-COV-001: Existing strategic surfaces UI-002 and UI-061 materially change. Active spec package must carry repo-truth map, tests, screenshots, and coverage close-out decision.
• TEST-GOV-001: Targeted Feature and Browser lanes are explicit. Browser cost is named and scoped.
• PROP-001 / BLOAT-001: No new source of truth, persisted entity, enum/status family, public abstraction, proof engine, or cross-domain UI framework.
• UI-FIL-001: Use native Filament components/shared primitives first; custom Blade must preserve Filament semantics, accessibility, dark mode, and one-primary-action hierarchy.
• Filament v5 / Livewire v4: Livewire v4.0+ compliance required. No Livewire v3 or Filament v3/v4 APIs.
• Panel provider location: panel providers remain in apps/platform/bootstrap/providers.php; no provider registration change expected.
• Global search: no resource global search change expected. If a resource is touched, it must retain safe View/Edit pages or disable global search.
• Destructive/high-impact actions: no destructive action introduced. Existing compare start remains confirmed/capability-gated/OperationRun-backed.
• Assets: no Filament asset registration expected; filament:assets deployment posture unchanged.

Current Repo Truth Summary

Existing verified Environment Dashboard surfaces:

• EnvironmentDashboard extends Filament Dashboard and renders EnvironmentDashboardContextChips, ManagedEnvironmentTriageArrivalContinuity, DashboardKpis, and EnvironmentDashboardOverview.
• EnvironmentDashboard::getUrl() resolves route-owned ManagedEnvironment and strips workspace/environment parameters into ManagedEnvironmentLinks::viewUrl().
• EnvironmentDashboardSummaryBuilder already derives context, posture, KPIs, recommended actions, governance status, readiness cards, active operation summary, and recent operations from existing models/services.
• Current dashboard view renders recommended actions, governance status, active operations requiring attention, and right-side readiness cards.
• Existing browser tests already assert dashboard context chips, KPI cards, readiness cards, ranked actions, and no table-first layout.

Existing verified Baseline Compare surfaces:

• BaselineCompareLanding is environment-owned at slug workspaces/{workspace}/environments/{environment}/baseline-compare.
• It rejects old workspace-style /admin/baseline-compare-landing?environment_id= URLs and remembered environment fallback.
• It strips legacy scope keys from generated URLs while preserving baseline_profile_id, subject_key, and nav.
• BaselineCompareStats::forTenant() derives states including no_tenant, no_assignment, no_snapshot, invalid_scope, comparing, failed, idle, and ready.
• Existing compare start action uses Action::make('compareNow')->requiresConfirmation()->action(...), BaselineCompareService::startCompare(), UiEnforcement, OperationUxPresenter, and OpsUxBrowserEvents.
• Current Blade already has explanation/stats, no-assignment/no-snapshot empty states, coverage warnings, evidence gap details, findings summaries, and diagnostics section; diagnostics are currently rendered when present and must become collapsed/default-secondary.

Known productization gaps:

• Environment Dashboard needs a more explicit decision card/question and proof/action panel instead of equal-weight dashboard sections.
• Environment Dashboard readiness dimensions should map to source truth and unavailable states in the spec map before implementation.
• Baseline Compare needs a first-read drift/action decision card, no-baseline actionable unavailable state, proof/disclosure panel, and raw diff/diagnostics collapsed by default.
• Baseline Compare must avoid false all-clear copy when zero findings coexist with evidence/coverage/trust gaps.

Existing Repository Surfaces Likely Affected

Runtime files, only during later implementation:

• 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
• apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-context-chips.blade.php
• apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
• apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummary.php
• apps/platform/app/Filament/Pages/BaselineCompareLanding.php
• apps/platform/resources/views/filament/pages/baseline-compare-landing.blade.php
• apps/platform/resources/lang/en/* and apps/platform/resources/lang/de/* only where touched copy follows existing localization conventions.

Tests, only during later implementation:

• apps/platform/tests/Feature/Filament/TenantDashboardTenantScopeTest.php
• apps/platform/tests/Feature/Filament/TenantDashboardDbOnlyTest.php
• apps/platform/tests/Feature/Rbac/DashboardRecoveryPostureVisibilityTest.php
• apps/platform/tests/Feature/Rbac/TenantDashboardArrivalContextVisibilityTest.php
• apps/platform/tests/Feature/Filament/BaselineCompareEnvironmentRouteContractTest.php
• apps/platform/tests/Feature/Filament/BaselineCompareLandingStartSurfaceTest.php
• apps/platform/tests/Feature/Filament/BaselineCompareExplanationSurfaceTest.php
• apps/platform/tests/Feature/Rbac/DriftLandingUiEnforcementTest.php
• apps/platform/tests/Feature/Navigation/Spec322AdminSurfaceScopeContractTest.php
• apps/platform/tests/Feature/Navigation/Spec322EnvironmentCtaUrlContractTest.php
• apps/platform/tests/Feature/ManagedEnvironment/ManagedEnvironmentCopyNeutralizationGuardTest.php
• apps/platform/tests/Browser/Spec330EnvironmentDashboardBaselineCompareSmokeTest.php

Spec/UI artifacts:

• specs/330-environment-dashboard-baseline-compare-productization/repo-truth-map.md
• screenshot artifacts under specs/330-environment-dashboard-baseline-compare-productization/artifacts/screenshots/
• optional UI coverage registry updates only if implementation materially changes route/archetype/coverage state.

Domain / Model Implications

• No new model, table, migration, enum, status family, persisted display state, or public service contract.
• Environment readiness must derive from:
  • ManagedEnvironment and workspace relation.
  • ProviderConnection status/health/consent/readiness fields.
  • ManagedEnvironmentPermission and required permissions view model.
  • TenantBackupHealthResolver, TenantBackupHealthAssessment, backup sets/schedules.
  • RestoreSafetyResolver and restore/recovery evidence presentation.
  • TenantGovernanceAggregateResolver, Finding, FindingException, and baseline compare stats.
  • EvidenceSnapshot, EnvironmentReview, ReviewPack, and related links.
  • OperationRun attention/freshness/outcome and OperationRunLinks.
• Baseline drift/action state must derive from:
  • BaselineTenantAssignment, BaselineProfile, BaselineSnapshot, BaselineSnapshotTruthResolver.
  • BaselineCompareStats, TenantGovernanceAggregate, BaselineCompareSummaryAssessment, operatorExplanation.
  • Finding drift findings/severity counts.
  • Evidence gap summaries/details and compare diagnostics only as secondary/collapsed context.
  • Existing compare OperationRun relation and links.

UI / Filament Implications

• Filament v5 and Livewire v4.0+ compliance must be preserved.
• Keep panel provider registration unchanged.
• Use Filament sections/buttons/badges/actions and existing shared primitives where suitable.
• Avoid fake charts, fake health, fake compliance, fake customer-safe, fake restore confidence, or generic KPI dashboard expansion.
• Environment Dashboard target order:
  • header/scope
  • main readiness decision card
  • readiness dimensions
  • right-side proof/action/disclosure panel
  • ranked next actions
  • operations/reviews/evidence/backup/provider details as secondary context
  • diagnostics collapsed
• Baseline Compare target order:
  • header/scope
  • main drift/action decision card
  • no-baseline visual Compare readiness stepper/pipeline and compact available inputs when compare is blocked by missing assignment
  • assignment / compare trust / drift summary only when a baseline-backed compare state exists
  • right-side evidence/proof/disclosure panel
  • findings/evidence-gap summary
  • raw diff/details collapsed or secondary

Livewire / Page State Implications

• Environment Dashboard and Baseline Compare must rely on route-owned environment context.
• Baseline Compare launch context (baseline_profile_id, subject_key, nav) remains initialization/query state only; it must not override environment ownership.
• Existing BaselineCompareLanding::monitoringPageStateContract() should remain consistent with Spec 198/319 contracts.
• Clean old workspace-style URLs and legacy query aliases must not establish environment context.
• Cross-workspace route mismatches stay 404.

RBAC / Policy Implications

Reuse existing authorization:

• Environment page visibility: environment membership and TENANT_VIEW.
• Provider permissions/readiness: required permissions routes and existing provider/permission capabilities.
• Backup posture: backup-set/schedule capabilities and policies.
• Restore/recovery proof: restore-run/backup capabilities and policies.
• Baseline compare view: environment access and TENANT_VIEW.
• Compare start: TENANT_SYNC through existing UiEnforcement.
• Baseline profile links: BaselineProfileResource authorization/policies.
• Drift findings: FindingResource / finding capabilities.
• Evidence snapshots: EvidenceSnapshotPolicy / evidence capability.
• Review and review packs: EnvironmentReviewResource, ReviewPackResource, policies.
• Operation proof: OperationRunPolicy and link helpers.
• Diagnostics/raw detail: SUPPORT_DIAGNOSTICS_VIEW or stricter existing raw/support capability.

No new permission semantics should be added unless implementation proves existing capabilities cannot express the action and spec/plan/tasks are updated first.

Audit / Observability Implications

• No new audit events are expected for read-only productization.
• Existing support diagnostics modal on Environment Dashboard already writes audit/telemetry and must remain authorized/redacted.
• Existing Baseline Compare start audit/OperationRun behavior remains unchanged.
• Do not imply OperationRun completion proves environment health or compare acceptability.

Test Strategy

Feature/Livewire tests:

• Repo truth map existence and required sections.
• Environment Dashboard decision layout.
• Environment Dashboard no false green when proof is missing.
• Environment Dashboard ranked next actions.
• Baseline Compare decision layout.
• Baseline Compare no-baseline actionable unavailable state.
• Baseline Compare drift/evidence state with raw details hidden by default.
• Diagnostics hidden/collapsed by default across both pages.
• Environment-owned route contract and legacy alias rejection.
• Static tenant platform-copy guard.
• RBAC for visible/hidden actions and raw diagnostics.

Browser tests:

• Explicit Environment Dashboard route non-empty/action-needed state.
• Explicit Baseline Compare route no-baseline state.
• Baseline Compare compare/drift state if fixtures support it.
• Diagnostics collapsed and raw details absent by default.
• Cross-workspace/invalid environment safe denial.
• Dynamic display name containing Tenant allowed, static tenant copy absent.
• Required screenshots under the Spec 330 artifacts path.

Validation:

• Targeted Feature/Livewire tests.
• Targeted Browser smoke.
• Context/route guard filter for EnvironmentDashboard, BaselineCompare, AdminSurfaceScope, EnvironmentOwned, LegacyTenant, and Spec322.
• pint --dirty.
• git diff --check.

Implementation Phases

Phase 1 - Repo Truth And Current UI Audit

• Inspect Environment Dashboard page/widget/summary builder/tests.
• Inspect Baseline Compare Landing page/view/stats/tests.
• Inspect Spec 325 target images/briefs and UI audit reports.
• Create/update repo-truth-map.md.
• Confirm exact source/capability/fallback for every visible element.
• Stop if a desired visible element requires new backend truth.

Phase 2 - Environment Dashboard Productization

• Add a first-read readiness question and decision card.
• Refine existing summary builder/widget payloads to expose status/reason/impact/proof/next-action without new state persistence.
• Add/right-size proof/action panel and ranked actions.
• Keep useful existing cards/details as secondary context.
• Collapse diagnostics/raw support by default.

Phase 3 - Baseline Compare Productization

• Add a first-read drift/action question and decision card.
• Render no-baseline/no-snapshot/no-compare states as actionable unavailable states.
• Show assignment, compare trust, drift impact, evidence/proof, and operation proof before findings/raw details.
• Collapse raw diff/diagnostics by default.
• Preserve existing compare start action semantics and matrix/detail links.

Phase 4 - Route, RBAC, Copy, And Disclosure Guards

• Verify route-owned environment context.
• Reject remembered fallback and legacy aliases.
• Guard cross-workspace mismatches.
• Gate/hide unavailable actions.
• Preserve dynamic names containing Tenant; remove static platform tenant copy.
• Ensure no false green claims.

Phase 5 - Browser Smoke And Screenshots

• Add browser smoke file.
• Create required screenshots where generated.
• Confirm diagnostics collapsed and raw details absent by default.
• Confirm no context drift.

Phase 6 - Validation And Close-Out

• Run focused Feature/Livewire/browser tests.
• Run targeted Spec 314-322 context guards.
• Run Pint and diff check.
• Report full suite status honestly.
• Record no migrations/packages/env/queues/storage/deployment assets/backcompat/legacy aliases.

Risk Controls

• Treat Spec 325 images as direction only; map every visible element to repo truth.
• Use unavailable/deferred states instead of inventing proof.
• Do not broaden Baseline Compare Matrix scope.
• Do not turn Environment Dashboard into a generic M365/admin-center status page.
• Keep OperationRun as execution proof, not health proof.
• Keep raw diagnostics collapsed/capability-gated.

Rollout / Deployment Considerations

• No migration expected.
• No seeders expected.
• No env var expected.
• No queue/scheduler/storage change expected.
• No package change expected.
• No deployment asset change expected unless implementation unexpectedly registers Filament assets; current expectation is no filament:assets change beyond existing deployment posture.
• Staging validation should focus on route-owned environment behavior, no-baseline/action-needed states, diagnostics collapsed, and no static tenant copy.

Candidate Selection Gate

Passed. Spec 330 was directly user-provided, is aligned with Spec 325 strategic target surfaces and post-Spec 329 follow-up sequencing, is not already present as an active/completed package, preserves completed Specs 314-329, and is scoped to two existing environment-owned pages.

Spec Readiness Gate

Expected pass after spec.md, plan.md, tasks.md, repo-truth-map.md, and checklists/requirements.md are generated and preparation analysis finds no blocking consistency issues.