ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/352-environment-dashboard-operator-guidance-consolidation/plan.md
ahmido 9a564d6bf2 feat: environment dashboard operator guidance consolidation (spec 352) (#423) 
Implemented the consolidated operator guidance panel for the environment dashboard. Updated EnvironmentDashboardSummaryBuilder to prioritize and select guidance based on the operator guidance contract. Added comprehensive unit, feature, and browser tests to verify the guidance selection logic and UI rendering.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #423
2026-06-04 12:56:02 +00:00

21 KiB
Raw Permalink Blame History

Implementation Plan: Spec 352 - Environment Dashboard Operator Guidance Consolidation

Branch: 352-environment-dashboard-operator-guidance-consolidation | Date: 2026-06-04 | Spec: specs/352-environment-dashboard-operator-guidance-consolidation/spec.md
Input: Direct user-provided Spec 352 draft plus repo truth from the implemented Spec 330 dashboard runtime and current review-output resolution-guidance surfaces.

Summary

Add one bounded dashboard-level operator guidance case over the existing Environment Dashboard runtime so the first read becomes:

  1. what needs attention first
  2. why it matters
  3. what the safest next action is
  4. where to go next

This follow-up must:

  • reuse the current Spec 330 dashboard layout and data model
  • optionally consume the current review-output resolution contract from Specs 350/351
  • preserve current proof panels, readiness dimensions, and secondary drilldowns
  • keep direct mutation ownership in the existing source surfaces

This follow-up must not:

  • rebuild the dashboard
  • reopen Baseline Compare
  • introduce a workflow engine or persistence
  • roll out new provider/governance/backup adapter families
  • hide residual Spec 351 browser follow-up under dashboard-local logic

Technical Context

Language/Version: PHP 8.4.15, Laravel 12.52.x
Primary Dependencies: Filament 5.2.x, Livewire 4.1.x, Pest 4, Tailwind CSS 4
Storage: PostgreSQL; no schema change expected
Testing: Pest Unit + Feature/Livewire + one bounded Browser smoke
Validation Lanes: fast-feedback + confidence + browser
Target Platform: apps/platform Laravel monolith, Sail-first locally
Project Type: server-rendered Filament web application
Performance Goals: keep render DB-only and bounded to current dashboard queries; no new remote calls during render; no new queue family
Constraints: no dashboard rebuild, no new persistence, no fake mutation CTA, no broad adapter rollout, no Graph calls during render, no cross-environment leakage, no duplicate primary action rails
Scale/Scope: one existing page, one summary-builder follow-up, one optional page-local selector/payload, one page-report update, one repo-truth map, one contract note

UI / Surface Guardrail Plan

  • Guardrail scope: changed strategic operator-facing surface
  • Affected routes/pages/actions/states/navigation/panel/provider surfaces:
    • /admin/workspaces/{workspace}/environments/{environment}
    • App\Filament\Pages\EnvironmentDashboard
    • apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php
    • current Environment Dashboard header action mirror
  • No-impact class, if applicable: N/A
  • Native vs custom classification summary: native Filament page plus existing custom Blade composition
  • Shared-family relevance: dashboard signals, action links, status messaging, proof links, header actions
  • State layers in scope: page and derived summary payload
  • Audience modes in scope: operator-MSP, manager, support where already authorized
  • Decision/diagnostic/raw hierarchy plan: one guidance case first, proof second, diagnostics third
  • Raw/support gating plan: keep current diagnostics disclosure collapsed; do not expand raw/support visibility
  • One-primary-action / duplicate-truth control: the new guidance case owns the dominant CTA; any existing ranked action list must not restate the same decision as a competing primary block
  • Handling modes by drift class or surface: review-mandatory
  • Repository-signal treatment: review-mandatory because a strategic first-screen dashboard surface is changing
  • Special surface test profiles: monitoring-state-page + global-context-shell
  • Required tests or manual smoke: Unit + Feature + one bounded Browser smoke
  • Exception path and spread control: if a generic cross-surface guidance framework appears necessary, stop and move that concern to a follow-up spec instead of widening the dashboard slice
  • Active feature PR close-out entry: Guardrail / Smoke Coverage
  • UI/Productization coverage decision: update the existing UI-002 page report only
  • Coverage artifacts to update: docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md
  • No-impact rationale: N/A
  • Navigation / Filament provider-panel handling: no route or provider-panel change
  • Screenshot or page-report need: yes; this is a strategic first-screen hierarchy change

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes
  • Systems touched:
    • App\Support\EnvironmentDashboard\EnvironmentDashboardSummaryBuilder
    • App\Support\EnvironmentDashboard\EnvironmentDashboardSummary
    • App\Filament\Pages\EnvironmentDashboard
    • current Environment Dashboard Blade view
    • App\Support\ResolutionGuidance\ResolutionCase
    • App\Support\ResolutionGuidance\ResolutionAction
    • App\Support\ResolutionGuidance\Adapters\ReviewPackOutputResolutionAdapter
    • App\Support\OperationRunLinks
  • Shared abstractions reused:
    • current dashboard recommendedActions() and readinessDecision() derivation
    • current dashboard proof and action helper methods
    • Spec 350/351 review-output resolution contract
    • current operation-proof link helper
  • New abstraction introduced? why?: maybe one page-local selector or payload normalizer; it is justified only if the current summary-builder arrays cannot express one explicit dominant guidance case without duplicating logic
  • Why the existing abstraction was sufficient or insufficient: current dashboard ranking is sufficient to detect important actions, but insufficient to expose one traceable top guidance case or to integrate review-output resolution semantics cleanly
  • Bounded deviation / spread control: any new helper stays under App\Support\EnvironmentDashboard\ and must not become a generic workflow or provider framework

OperationRun UX Impact

  • Touches OperationRun start/completion/link UX?: yes, deep-link semantics only
  • Central contract reused: App\Support\OperationRunLinks
  • Delegated UX behaviors: unchanged; the dashboard can link to operation proof/detail, but it must not start or reshape run lifecycle behavior
  • Surface-owned behavior kept local: selection and ranking of when operation proof becomes the dominant or secondary follow-up
  • Queued DB-notification policy: unchanged
  • Terminal notification path: unchanged
  • Exception path: none

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: yes
  • Provider-owned seams: required permissions, provider readiness detail, verification-owned follow-up routes
  • Platform-core seams: environment guidance payload, dashboard ranking, operator-facing top guidance vocabulary
  • Neutral platform terms / contracts preserved: environment, provider, required permissions, evidence, operation proof, review output, operator guidance
  • Retained provider-specific semantics and why: provider-specific permission or verification language remains only where current provider-owned surfaces already require it
  • Bounded extraction or follow-up path: none in this slice; any deeper provider productization stays a follow-up spec

Current Repo Truth Summary

  • Spec 330 already implemented the current dashboard contract:
    • main readiness decision card
    • readiness dimensions
    • readiness proof panel
    • supporting signals
    • ranked recommended actions
    • collapsed diagnostics
  • EnvironmentDashboardSummaryBuilder::recommendedActions() currently ranks page-local candidates and returns the top three. Current observed candidate order is:
    • required permissions
    • delegated permissions
    • high-severity findings
    • operations requiring attention
    • overdue findings
    • risk exceptions
    • recovery posture
    • continue review
  • EnvironmentDashboardSummaryBuilder::readinessDecision() currently mirrors the first ranked recommended action for reason, impact, and next-action text rather than using a dedicated dashboard guidance contract.
  • EnvironmentDashboard header actions currently mirror the first recommended action and certain readiness cards, again without an explicit operator_guidance payload.
  • ReviewPackOutputResolutionAdapter exists and already carries bounded review-output guidance, but the dashboard does not consume it today.
  • docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md still calls for one stronger primary posture decision and calmer proof hierarchy.
  • Governance follow-up remains owned by the current Governance Inbox/runtime from Spec 346; this slice may route into that surface but must not reopen or close it.
  • Spec 351 provides repo-real review-output action semantics, but its browser audit still records residual P2 follow-up observations. The dashboard may reuse stable action semantics but must not depend on unresolved workflow polish.

Constitution Check

GATE: Must pass before implementation. This prep keeps the design inside the already-proven dashboard and guidance boundaries.

  • Inventory-first: satisfied; all dashboard truth remains derived from current observed/environment-owned records
  • Read/write separation: satisfied; the dashboard remains navigation-first in this slice
  • Graph contract path: satisfied; no new Graph work is introduced
  • Deterministic capabilities: satisfied; linked destinations keep current capability and policy checks
  • Workspace isolation: satisfied; the surface remains route-owned and environment-bound
  • Tenant isolation: satisfied; no cross-environment or cross-workspace shortcut is introduced
  • OperationRun observability: satisfied; only existing run links are reused
  • Test governance: satisfied; narrow Unit + Feature + Browser proof is planned explicitly
  • Proportionality / anti-bloat: satisfied if any new helper remains page-local, derived-only, and narrowly justified
  • Shared pattern first: satisfied by reusing the current summary builder and existing resolution contract before adding anything new
  • Provider boundary: satisfied if provider-specific vocabulary stays inside existing provider-owned follow-up surfaces
  • UI/Productization coverage: satisfied via the explicit UI-002 follow-up and page-report update

Test Governance Check

  • Test purpose / classification by changed surface: Unit for ranking/selection, Feature for summary/view integration and scope, Browser for first-screen hierarchy
  • Affected validation lanes: fast-feedback, confidence, browser
  • Why this lane mix is the narrowest sufficient proof: the change is deterministic presentation and routing logic over an existing strategic page, not a schema or infrastructure change
  • Narrowest proving command(s):
    • cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php --compact
    • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php --compact
    • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php --compact
  • Fixture / helper / factory / seed / context cost risks: keep existing dashboard/review-output/provider fixtures narrow; do not widen default support contexts
  • Expensive defaults or shared helper growth introduced?: no
  • Heavy-family additions, promotions, or visibility changes: one explicit browser smoke only
  • Surface-class relief / special coverage rule: monitoring-state-page + global-context-shell
  • Closing validation and reviewer handoff: re-run Environment Dashboard, Spec 330, Spec 350, Spec 351, and ResolutionGuidance filtered proofs; verify no-action, provider-priority, and environment-scope behavior
  • Budget / baseline / trend follow-up: none expected
  • Review-stop questions: did we introduce a second framework, a fake CTA, or duplicate primary decision copy?
  • Escalation path: document-in-feature unless broader domain rewrites are uncovered, then follow-up-spec
  • Active feature PR close-out entry: Guardrail / Smoke Coverage
  • Why no dedicated follow-up spec is needed: this slice stays limited to the Environment Dashboard and reuses current owner surfaces

Implementation Approach

Phase 0 - Repo Truth Gate

  1. Re-read spec.md, plan.md, tasks.md, repo-truth-map.md, contracts/environment-dashboard-operator-guidance-contract.md, and checklists/requirements.md.
  2. Re-read historical context only:
    • specs/330-environment-dashboard-baseline-compare-productization/*
    • specs/338-workspace-environment-resource-scope-contract/*
    • specs/346-governance-inbox-final-operator-workflow/*
    • specs/350-operator-resolution-guidance-framework-v1/*
    • specs/351-review-output-resolve-actions-v1/*
  3. Re-verify the current runtime truth in:
    • apps/platform/app/Filament/Pages/EnvironmentDashboard.php
    • apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
    • apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummary.php
    • apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php
    • apps/platform/app/Support/ResolutionGuidance/Adapters/ReviewPackOutputResolutionAdapter.php
    • existing review, evidence, operation, and required-permissions link helper paths used by the dashboard
  4. Keep repo-truth-map.md and the dashboard contract note current if runtime inspection changes the narrowest safe selection model.
  5. Confirm no schema, package, env var, queue family, scheduler, storage, panel/provider, or global-search change is required.

Phase 1 - Tests First

  1. Add apps/platform/tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php.
  2. Cover deterministic selection for:
    • provider blocker outranks review-output follow-up when current repo truth supports both
    • review-output follow-up appears when provider blockers are absent and a stable case exists
    • operation attention or existing ranked dashboard signals become dominant when higher-order cases are absent
    • calm no-action fallback
  3. Add apps/platform/tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php.
  4. Cover:
    • one dominant top guidance case renders
    • environment-scoped primary and secondary links
    • no fake mutation CTA in the guidance block
    • current proof panels/cards remain visible
  5. Add apps/platform/tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php.
  6. Prove at least:
    • action-needed/provider-blocker state
    • review-output-driven state if fixture support is available
    • no-urgent-action state if fixture support is available
  7. Reuse Spec 330, Spec 350, and Spec 351 filtered coverage rather than copying their full assertions. Re-run Spec 346 only if the final dashboard mapping changes governance-owned link or action-shape behavior.

Phase 2 - Guidance Contract And Selector

  1. Choose the narrowest implementation shape:
    • prefer extending the current summary-builder payload with operatorGuidance
    • add a dedicated selector/helper only if the builder methods become hard to review
  2. Build one derived payload with:
    • key
    • severity / tone
    • status
    • title
    • reason
    • impact
    • one primaryAction
    • optional secondaryActions
    • source refs / helper details where useful
  3. Feed the selector from existing dashboard/runtime truth:
    • current recommendedActions
    • current governanceStatus
    • current readinessCards
    • current activeOperationSummary
    • current review/review-pack environment state for optional review-output reuse
  4. Keep the selector derived-only and request-scoped.
  5. Do not create a generic cross-page framework if a page-local dashboard helper is enough.

Phase 3 - Candidate Ranking And Review-Output Reuse

  1. Use the current dashboard ranking as the baseline ordering model.
  2. Add bounded priority normalization only where current repo truth clearly supports it:
    • provider blockers / required permissions
    • stable review-output resolution case
    • operation attention or evidence/proof follow-up
    • current findings/risk/recovery/dashboard candidates
    • calm no-action fallback
  3. If a review-output case is consumed:
    • only consume it when the target review/action is already repo-real and environment-scoped
    • do not invent a dashboard-local review workflow
    • do not depend on unresolved Spec 351 browser polish
  4. Keep provider-specific detail inside the existing provider-owned routes and current dashboard helper text.

Phase 4 - Dashboard Integration

  1. Update EnvironmentDashboardSummary and EnvironmentDashboardSummaryBuilder so the top card can render from operatorGuidance rather than mirroring recommendedActions[0] directly.
  2. Update apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php to render:
    • one dominant guidance block
    • subordinate secondary links
    • a productized no-action state
  3. Keep current readiness dimensions, proof panel, supporting signals, and diagnostics disclosure intact as secondary context.
  4. Update App\Filament\Pages\EnvironmentDashboard header actions so the mirrored primary action follows the new guidance payload instead of the raw ranked-action array.
  5. Avoid duplicating the same reason/impact/next-action content in several equal-weight blocks.

Phase 5 - Copy, Audit, And Browser Proof

  1. Update only the required localization keys in:
    • apps/platform/lang/en/localization.php
    • apps/platform/lang/de/localization.php
  2. Keep operator wording practical:
    • Needs attention
    • No urgent operator action
    • Recommended next action
    • existing source-owned labels where already repo-real
  3. Update docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md for the new top-guidance hierarchy.
  4. Capture screenshots under specs/352-environment-dashboard-operator-guidance-consolidation/artifacts/screenshots/.

Phase 6 - Validation And Close-Out

  1. Run focused Spec 352 Unit, Feature, and Browser coverage.
  2. Re-run filtered regressions for:
    • EnvironmentDashboard
    • Spec330
    • Spec350
    • Spec351
    • ResolutionGuidance
  3. Run pint --dirty and git diff --check.
  4. Report any broader failure honestly without widening scope.

Project Structure

Documentation (this feature)

specs/352-environment-dashboard-operator-guidance-consolidation/
├── spec.md
├── plan.md
├── tasks.md
├── repo-truth-map.md
├── contracts/
│   └── environment-dashboard-operator-guidance-contract.md
└── checklists/
    └── requirements.md

Likely Runtime Surfaces

apps/platform/app/Filament/Pages/EnvironmentDashboard.php
apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummary.php
apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php
apps/platform/lang/en/localization.php
apps/platform/lang/de/localization.php
apps/platform/tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php
apps/platform/tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php
apps/platform/tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php
docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md

ios/ or android/ └── [platform-specific structure: feature modules, UI flows, platform tests]


**Structure Decision**: [Document the selected structure and reference the real
directories captured above]

## Complexity Tracking

> **Fill when Constitution Check has violations that must be justified OR when BLOAT-001 is triggered by new persistence, abstractions, states, or semantic frameworks.**

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

## Proportionality Review

> **Fill when the feature introduces a new enum/status family, DTO/presenter/envelope, persisted entity/table/artifact, interface/contract/registry/resolver, taxonomy/classification system, or cross-domain UI framework.**

- **Current operator problem**: [What present-day workflow or risk requires this?]
- **Existing structure is insufficient because**: [Why the current code cannot serve safely or clearly]
- **Narrowest correct implementation**: [Why this shape is the smallest viable one]
- **Ownership cost created**: [Maintenance, testing, cognitive load, migration, or review burden]
- **Alternative intentionally rejected**: [Simpler option and why it failed]
- **Release truth**: [Current-release truth or future-release preparation]