TenantAtlas/specs/352-environment-dashboard-operator-guidance-consolidation/contracts/environment-dashboard-operator-guidance-contract.md

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

[
    '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 ResolutionActions 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.