# Environment Dashboard Operator Guidance Contract

Status: implemented  
Spec: `specs/352-environment-dashboard-operator-guidance-consolidation/spec.md`  
Date: 2026-06-04

## Purpose

Define the narrowest derived payload needed for the Environment Dashboard top guidance area.

This contract is:

- derived-only
- request-scoped
- environment-scoped
- navigation-first

This contract is not:

- persisted truth
- a generic workflow engine
- a provider framework
- a replacement for current owner-surface action safety

## Implemented Payload Shape

```php
[
    'key' => 'review_output.publication_blocked',
    'tone' => 'warning',
    'status' => 'Blocked',
    'title' => 'Draft review exists',
    'reason' => 'Open the draft review to refresh inputs before publication.',
    'impact' => 'The latest released review output should not be treated as customer-ready until the draft is resolved.',
    'actionLabel' => 'Open draft review',
    'actionUrl' => '...',
    'actionDisabled' => false,
    'secondaryActions' => [
        [
            'key' => 'resolve_review_blockers',
            'actionLabel' => 'Inspect review blockers',
            'actionUrl' => '...',
            'actionDisabled' => false,
            'helperText' => null,
        ],
        [
            'key' => 'open_evidence_basis',
            'actionLabel' => 'Open evidence basis',
            'actionUrl' => '...',
            'actionDisabled' => false,
            'helperText' => null,
        ],
    ],
    'source' => [
        'type' => 'review_output_resolution',
        'key' => 'review_output.publication_blocked',
    ],
    'helperText' => null,
]
```

## Selection Rules

Use the current dashboard ranking as the baseline source of truth, then apply only bounded normalization where current repo truth clearly supports it.

Preferred order:

1. provider blocker / required permissions
2. stable review-output resolution case
3. operation attention
4. current dashboard findings / overdue findings
5. risk exceptions
6. recovery posture
7. continue review
8. calm no-action fallback

## Safety Rules

- The dashboard guidance block should prefer navigation over direct mutation.
- If a linked target is not repo-real or not authorized, degrade to a truthful unavailable or detail-review fallback.
- The dashboard must not invent review, provider, governance, or backup workflows that do not already exist on owner surfaces.
- The dashboard must not introduce a second equal-weight primary CTA outside the selected `primaryAction`.

In the implemented runtime this means:

- review-output `ResolutionAction`s are flattened into navigation-only `actionLabel` / `actionUrl` fields
- executable review actions such as `createNextReview`, `refreshReview`, or `publishReview` are not mounted from the dashboard
- source-owned actions remain available only on the linked owner surfaces

## Known Current Inputs

- current `recommendedActions`
- current `governanceStatus`
- current `readinessCards`
- current `activeOperationSummary`
- optional review-output `ResolutionCase`
- latest relevant review-output review selected by `latestReviewOutputReview()`

## Known Current Outputs To Preserve

- readiness dimensions
- readiness proof panel
- supporting signals
- collapsed diagnostics
- environment-scoped header follow-up mirror

## Implementation Notes

- The dashboard continues to keep `recommendedActions` for secondary follow-up, but the top card no longer mirrors `recommendedActions[0]`.
- `reviewOutputOperatorGuidance()` consumes `ReviewPackOutputResolutionAdapter` and decorates successor-draft cases with the same `Draft review exists` copy already used by `CustomerReviewWorkspace`.
- The Blade view removes any secondary recommended action whose label and URL match the dominant guidance CTA.