# 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)

```text
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

```text
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]