ahmido
9a564d6bf2
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
126 lines
11 KiB
Markdown
126 lines
11 KiB
Markdown
# Tasks: Spec 352 - Environment Dashboard Operator Guidance Consolidation
|
|
|
|
**Input**: `specs/352-environment-dashboard-operator-guidance-consolidation/spec.md`, `plan.md`, `repo-truth-map.md`, `contracts/environment-dashboard-operator-guidance-contract.md`, and `checklists/requirements.md`
|
|
|
|
**Tests**: Required. This is a strategic dashboard selection, hierarchy, and scope-safety change over an existing Environment Dashboard surface.
|
|
|
|
## Test Governance Checklist
|
|
|
|
- [x] Lane assignment is explicit and narrow: Unit for selection/ranking, Feature for dashboard integration and scope, Browser for first-screen hierarchy proof.
|
|
- [x] New or changed tests stay in the smallest honest family, and the browser addition is explicit.
|
|
- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay cheap by default.
|
|
- [x] Planned validation commands cover the change without pulling in unrelated lane cost.
|
|
- [x] The declared surface profiles (`monitoring-state-page` and `global-context-shell`) are explicit.
|
|
- [x] Any new helper remains derived-only and does not create hidden persistence or a workflow engine.
|
|
|
|
## Phase 1: Preparation And Repo Truth
|
|
|
|
**Purpose**: Keep the implementation bounded to the existing Environment Dashboard runtime and current resolution-guidance truth.
|
|
|
|
- [x] T001 Re-read `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, `contracts/environment-dashboard-operator-guidance-contract.md`, and `checklists/requirements.md`.
|
|
- [x] T002 Re-read related historical context only: Specs 330, 338, 346, 350, and 351. Do not modify their artifacts.
|
|
- [x] T003 Re-verify the current Environment Dashboard runtime truth in `apps/platform/app/Filament/Pages/EnvironmentDashboard.php`, `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummary.php`, `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php`, and `apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php`.
|
|
- [x] T004 Re-verify the current dashboard header-action mirror and follow-up hierarchy in `apps/platform/app/Filament/Pages/EnvironmentDashboard.php`.
|
|
- [x] T005 Re-verify the current review-output guidance truth in `apps/platform/app/Support/ResolutionGuidance/Adapters/ReviewPackOutputResolutionAdapter.php`, `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`, and `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`.
|
|
- [x] T006 Confirm no migration, package, env var, queue family, scheduler, storage, deployment asset, panel/provider, or global-search change is required; confirm Filament v5 / Livewire v4.0+ and `apps/platform/bootstrap/providers.php` remain unchanged.
|
|
- [x] T007 Keep `repo-truth-map.md` and `contracts/environment-dashboard-operator-guidance-contract.md` current if runtime inspection reveals a narrower or broader safe selection model.
|
|
- [x] T008 Explicitly document whether residual Spec 351 browser observations affect dashboard reuse; if they do, keep dashboard mapping on stable repo-real navigation semantics only.
|
|
|
|
## Phase 2: Tests First
|
|
|
|
**Purpose**: Lock deterministic guidance selection, scope, and one-primary-action behavior before runtime changes.
|
|
|
|
- [x] T009 Add `apps/platform/tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php`.
|
|
- [x] T010 Add unit assertions that provider-readiness blockers outrank lower-priority review-output or dashboard follow-up when the current repo truth supports both candidates.
|
|
- [x] T011 Add unit assertions that review-output guidance can become dominant when provider blockers are absent and a stable environment-scoped case/action exists.
|
|
- [x] T012 Add unit assertions that existing dashboard signals such as operations attention or current ranked candidates can become dominant when higher-order cases are absent.
|
|
- [x] T013 Add unit assertions for the calm `No urgent operator action` fallback.
|
|
- [x] T014 Add `apps/platform/tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php`.
|
|
- [x] T015 Add feature assertions that the dashboard renders one explicit top guidance case with one dominant primary action.
|
|
- [x] T016 Add feature assertions that primary and secondary links remain environment-scoped and authorization-aware.
|
|
- [x] T017 Add feature assertions that readiness dimensions, proof items, and supporting signals remain visible as secondary context.
|
|
- [x] T018 Add feature assertions that no fake direct mutation CTA is rendered in the top guidance area.
|
|
- [x] T019 Add `apps/platform/tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php`.
|
|
- [x] T020 Browser Flow A: provider-blocker state; assert one dominant top guidance case, one primary CTA, subordinate secondary links, and collapsed diagnostics.
|
|
- [x] T021 Browser Flow B: review-output-driven state if fixture-supported; assert review follow-up is dominant only when provider blockers are absent and the action target is repo-real.
|
|
- [x] T022 Browser Flow C: calm no-action state if fixture-supported; assert a productized no-urgent-action message and preserved secondary proof surfaces.
|
|
|
|
## Phase 3: Guidance Contract And Selector
|
|
|
|
**Purpose**: Add the narrowest derived dashboard guidance payload over the current summary-builder truth.
|
|
|
|
- [x] T023 Update `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummary.php` only if needed to carry one derived `operatorGuidance` payload; do not add persisted state or public framework semantics.
|
|
- [x] T024 Update `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php` to derive one explicit dashboard guidance case from current dashboard/runtime truth.
|
|
- [ ] T025 Only if the summary builder becomes hard to review, add a bounded helper under `apps/platform/app/Support/EnvironmentDashboard/` for guidance selection; keep it page-local, derived-only, and request-scoped.
|
|
- [x] T026 Keep ranking grounded in current dashboard candidate priorities and add bounded precedence for provider blockers and stable review-output cases only where repo truth clearly supports it.
|
|
- [x] T027 Consume `ReviewPackOutputResolutionAdapter` only for stable environment-scoped dashboard reuse; do not invent open-draft discovery or a dashboard-local review workflow.
|
|
- [x] T028 Build the guidance payload with status, reason, impact, one primary action, subordinate secondary actions, source references where useful, and an honest no-action fallback.
|
|
- [x] T029 Do not introduce a new provider/governance/backup adapter family, a new persisted truth model, or a new enum/status family in this slice.
|
|
|
|
## Phase 4: Dashboard Integration
|
|
|
|
**Purpose**: Render the new guidance contract without reopening the Spec 330 dashboard productization work.
|
|
|
|
- [x] T030 Update `apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php` so the top decision area renders from the new `operatorGuidance` payload.
|
|
- [x] T031 Preserve current readiness dimensions, readiness proof panel, supporting signals, and diagnostics disclosure as secondary context.
|
|
- [x] T032 Demote or deduplicate the current ranked `recommendedActions` section so it does not compete with the top guidance case.
|
|
- [x] T033 Update `apps/platform/app/Filament/Pages/EnvironmentDashboard.php` so the mirrored header primary/secondary follow-up actions use the new guidance payload rather than raw first-ranked action data.
|
|
- [x] T034 Keep the dashboard navigation-first in this slice; do not add direct new mutation execution in the top guidance block.
|
|
- [x] T035 Render a calm `No urgent operator action` state with an honest next step when no dominant case exists.
|
|
|
|
## Phase 5: Copy, Audit, And Browser Proof
|
|
|
|
**Purpose**: Align visible copy and coverage artifacts with the new guidance hierarchy.
|
|
|
|
- [x] T036 Update only the required dashboard guidance copy in `apps/platform/lang/en/localization.php`.
|
|
- [x] T037 Update matching dashboard guidance copy in `apps/platform/lang/de/localization.php`.
|
|
- [x] T038 Update `docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md` for the new top-guidance hierarchy and preserved secondary proof model.
|
|
- [x] T039 Capture screenshots under `specs/352-environment-dashboard-operator-guidance-consolidation/artifacts/screenshots/`.
|
|
- [x] T040 Keep `repo-truth-map.md` and `contracts/environment-dashboard-operator-guidance-contract.md` aligned with the final bounded implementation shape.
|
|
|
|
## Phase 6: Validation
|
|
|
|
**Purpose**: Prove the guidance contract stays bounded and preserves current scope and trust rules.
|
|
|
|
- [x] T041 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php --compact`.
|
|
- [x] T042 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php --compact`.
|
|
- [x] T043 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php --compact`.
|
|
- [x] T044 Confirm the final implementation keeps the Environment Dashboard render path DB-local and does not introduce `GraphClientInterface` or provider API calls from `EnvironmentDashboard`, `EnvironmentDashboardSummaryBuilder`, or any newly touched guidance helper/view path.
|
|
- [x] T045 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=EnvironmentDashboard`.
|
|
- [x] T046 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec330`.
|
|
- [x] T047 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec350`.
|
|
- [x] T048 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec351`.
|
|
- [x] T049 Run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ResolutionGuidance`.
|
|
- [x] T050 Governance-owned link or action-shape behavior did not change; `Spec346` rerun was not required for this slice.
|
|
- [x] T051 Run `cd apps/platform && ./vendor/bin/sail pint --dirty`.
|
|
- [x] T052 Run `git diff --check`.
|
|
- [x] T053 Report any out-of-scope broader-suite or fixture gaps honestly if they remain outside this slice.
|
|
|
|
## Non-Goals Checklist
|
|
|
|
- [ ] NT001 Do not rebuild Environment Dashboard from scratch.
|
|
- [ ] NT002 Do not reopen Baseline Compare productization.
|
|
- [ ] NT003 Do not create a new persisted dashboard state, workflow engine, or adapter family.
|
|
- [ ] NT004 Do not hide residual Spec 351 browser observations by moving them into dashboard-local semantics.
|
|
- [ ] NT005 Do not add direct new mutation execution to the dashboard guidance area.
|
|
- [ ] NT006 Do not add portal, PDF/HTML, PSA, AI, queue, storage, or deployment follow-up work.
|
|
|
|
## Required Final Report Content
|
|
|
|
When implementation later completes, report:
|
|
|
|
- changed dashboard guidance behavior
|
|
- dominant-case selection model
|
|
- provider/review-output/no-action behavior
|
|
- environment-scope guarantees
|
|
- preserved secondary proof surfaces
|
|
- files changed
|
|
- repo-truth-map status
|
|
- contract note status
|
|
- tests run and results
|
|
- explicit render-path check result for no `GraphClientInterface` or provider API calls during dashboard render
|
|
- browser verification and screenshot path
|
|
- known gaps
|
|
- full-suite run/not run
|
|
- explicit no migrations/packages/env/queues/scheduler/storage/deployment-assets statement
|