# Repo Truth Map: Spec 352 - Environment Dashboard Operator Guidance Consolidation

Status: implemented  
Branch: `352-environment-dashboard-operator-guidance-consolidation`  
Date: 2026-06-04

## Scope Boundary

Spec 352 is a narrow follow-up over the implemented Environment Dashboard runtime from Spec 330.

It may:

- refine the top guidance contract on the existing Environment Dashboard
- reuse current dashboard summary data
- optionally consume current review-output resolution guidance where the action target is already repo-real

It may not:

- rebuild the page
- reopen Baseline Compare
- create new persistence
- add new provider/governance/backup adapter families
- hide unresolved Spec 351 browser observations inside dashboard-local semantics

## Current Primary Surface

| Area | Current repo truth | Notes |
|---|---|---|
| Page class | `apps/platform/app/Filament/Pages/EnvironmentDashboard.php` | Existing environment-owned route/page |
| Summary builder | `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php` | Current source for dashboard payload |
| Summary payload | `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummary.php` | Existing derived request-scoped summary |
| Main view | `apps/platform/resources/views/filament/widgets/dashboard/environment-dashboard-overview.blade.php` | Existing decision-first layout from Spec 330 |
| Page report | `docs/ui-ux-enterprise-audit/page-reports/ui-002-environment-dashboard.md` | Still calls for a stronger single primary posture decision |

## Implemented Runtime Follow-up

- `EnvironmentDashboardSummary` now carries a derived `operatorGuidance` payload.
- `EnvironmentDashboardSummaryBuilder` now derives `operatorGuidance` before `readinessDecision`, so the top card and the page header mirror the same dominant case.
- `latestReviewOutputReview()` was added so a newer successor draft does not hide the published or superseded review-output state that should still drive dashboard follow-up.
- Review-output reuse is bounded to `ReviewPackOutputResolutionAdapter` plus dashboard-local mapping that strips direct mutation execution from the dashboard surface.
- The main widget view now renders secondary review-output links as compact subordinate links and filters the old recommended-actions rail so it does not restate the dominant decision.
- `EnvironmentDashboard` header actions now mirror `operatorGuidance` instead of the old first-ranked-action shortcut.

## Current Dashboard Guidance Truth

### What already exists

- `readinessDecision`
- `recommendedActions`
- `governanceStatus`
- `readinessCards`
- `readinessDimensions`
- `readinessProofPanel`
- header action mirroring inside `EnvironmentDashboard`

### How the current top decision is now chosen

- `EnvironmentDashboardSummaryBuilder::recommendedActions()` still assembles current repo-backed candidate actions for secondary follow-up.
- `EnvironmentDashboardSummaryBuilder::operatorGuidance()` now selects the dominant case in this order:
  1. provider blockers from recommended actions
  2. stable review-output resolution case from the latest relevant output review
  3. operations attention
  4. high-severity findings / overdue findings
  5. risk exceptions
  6. recovery posture
  7. continue review
  8. calm no-action fallback
- `EnvironmentDashboardSummaryBuilder::readinessDecision()` now mirrors `operatorGuidance`, not `recommendedActions[0]`.
- `EnvironmentDashboard` header actions mirror `operatorGuidance` and its secondary actions.

### Current observed candidate order in `recommendedActions()`

| Priority | Key | Source class / truth |
|---:|---|---|
| 10 | `required_permissions` | required-permissions overview / provider blocker |
| 20 | `delegated_permissions` | required-permissions overview / lower-severity provider blocker |
| 30 | `high_severity_findings` | governance aggregate / active findings |
| 35 | `operations_requiring_attention` | current environment `OperationRun` attention query |
| 40 | `overdue_findings` | governance aggregate / overdue findings |
| 50 | `risk_exceptions` | exception stats + governance counters |
| 60 | `recovery_posture` | backup/recovery posture helpers |
| 80 | `continue_review` | latest review / latest review pack state |

This ordering is now repo-real current behavior.

## Current Secondary Proof Truth

| Payload area | Current repo truth | Notes |
|---|---|---|
| `governanceStatus` | baseline compare, evidence coverage, review freshness, provider permissions, backup posture | Secondary proof/status signals |
| `readinessCards` | current review, risk exceptions, provider health, customer-safe output | Secondary summary cards |
| `readinessProofPanel` | selected proof-path items + optional review-pack + operation proof | Secondary proof panel |
| `supportingSignals` | additional readiness signals | Secondary table-style support surface |
| `diagnosticsDisclosure` | collapsed diagnostics summary | Raw/support detail remains collapsed |

## Review-Output Reuse Truth

| Area | Current repo truth | Status for Spec 352 |
|---|---|---|
| `ReviewPackOutputResolutionAdapter` | exists under `App\Support\ResolutionGuidance\Adapters\ReviewPackOutputResolutionAdapter` | available for bounded reuse |
| `ResolutionCase` / `ResolutionAction` | exist from Spec 350 | available for bounded reuse |
| Review-output resolve actions | repo-real through Spec 351 | available for bounded reuse |
| Dashboard consumer of resolution guidance | none found | gap this spec may close narrowly |
| Dashboard consumer of resolution guidance | `EnvironmentDashboardSummaryBuilder::reviewOutputOperatorGuidance()` | implemented narrow reuse |

## Dependency Guardrail Notes

| Dependency | Current repo truth | Guardrail for Spec 352 |
|---|---|---|
| Spec 330 | implemented; `repo-truth-map.md` says `Status: implemented` and tasks are checked | treat as completed baseline; do not reopen layout or Baseline Compare scope |
| Spec 338 | route/scope contract foundation | keep environment-owned route truth unchanged |
| Spec 346 | Governance Inbox operator workflow remains the adjacent governance-owner follow-up surface and is explicitly not closed | reuse linked destination truth only; do not absorb governance workflow ownership into the dashboard |
| Spec 350 | checked implementation tasks and shared guidance contract | reuse if helpful; do not broaden |
| Spec 351 | checked implementation tasks and committed runtime follow-through, but residual browser-audit notes remain | reuse only stable action semantics; do not hide unresolved follow-up |

## Implemented Narrow Slice

The current dashboard now has:

1. one explicit environment guidance contract
2. a stable merge point between dashboard ranking and review-output resolution guidance
3. a productized calm `No urgent operator action` state
4. a deduplicated relationship between the top guidance area, ranked actions, and mirrored header actions

Preserved:

- current route ownership
- current proof panels and secondary cards
- current source-owned action safety
- current collapsed diagnostics model

## Evidence

- Unit: `tests/Unit/EnvironmentDashboard/Spec352EnvironmentDashboardGuidanceSelectionTest.php`
- Feature: `tests/Feature/Filament/Spec352EnvironmentDashboardGuidanceTest.php`
- Browser: `tests/Browser/Spec352EnvironmentDashboardGuidanceSmokeTest.php`
- Screenshots:
  - `specs/352-environment-dashboard-operator-guidance-consolidation/artifacts/screenshots/spec352-environment-dashboard-provider-blocker.png`
  - `specs/352-environment-dashboard-operator-guidance-consolidation/artifacts/screenshots/spec352-environment-dashboard-review-output.png`
  - `specs/352-environment-dashboard-operator-guidance-consolidation/artifacts/screenshots/spec352-environment-dashboard-no-urgent-action.png`