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
112 lines
3.7 KiB
Markdown
112 lines
3.7 KiB
Markdown
# 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.
|