ahmido
4cf2712f92
Implemented the first version of the operator resolution guidance framework. Added new foundation classes (ResolutionCase, ResolutionAction) and a ReviewPackOutputResolutionAdapter. Updated the Customer Review Workspace and Environment Review Resource to use the new adapter. Added extensive test coverage for the framework and UI integrations. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #421
150 lines
4.5 KiB
Markdown
150 lines
4.5 KiB
Markdown
# Resolution Case Contract
|
|
|
|
Status: Draft for Spec 350
|
|
Scope: Derived operator-guidance envelope only
|
|
|
|
## Purpose
|
|
|
|
`ResolutionCase` is the shared productized guidance object for current-release operator issues that already exist in repo truth.
|
|
|
|
It answers:
|
|
|
|
1. What is wrong?
|
|
2. Why does it matter?
|
|
3. What is the dominant next step?
|
|
4. Is that step navigation/disclosure-only or an existing safe executable path?
|
|
5. Which source records prove this guidance?
|
|
|
|
This contract must wrap existing guidance producers. It must not replace them or persist a second truth model.
|
|
|
|
## Design Constraints
|
|
|
|
- Derived only; no persistence
|
|
- Scope explicit
|
|
- Exactly one primary action
|
|
- Source-traceable
|
|
- Safe-execution aware
|
|
- Provider-neutral in the core contract
|
|
- Technical details secondary
|
|
|
|
## Required Shape
|
|
|
|
```php
|
|
[
|
|
'key' => 'review_pack.output_not_customer_ready',
|
|
'scope' => [
|
|
'type' => 'environment',
|
|
'workspace_id' => 1,
|
|
'managed_environment_id' => 41,
|
|
'source_surface' => 'customer_review_workspace',
|
|
],
|
|
'severity' => 'warning',
|
|
'status' => 'action_required',
|
|
|
|
'title' => 'Output not customer-ready',
|
|
'reason' => 'The published review is based on incomplete evidence.',
|
|
'impact' => 'This review pack should not be shared externally until the evidence basis is refreshed.',
|
|
|
|
'primary_action' => [
|
|
'key' => 'environment_review.open_current_limitations',
|
|
'label' => 'Inspect review blockers',
|
|
'type' => 'navigation',
|
|
'url' => '...',
|
|
'capability' => null,
|
|
'requires_confirmation' => false,
|
|
'audit_event' => null,
|
|
'operation_run_type' => null,
|
|
],
|
|
|
|
'secondary_actions' => [
|
|
[
|
|
'key' => 'evidence.open_basis',
|
|
'label' => 'Open evidence basis',
|
|
'type' => 'navigation',
|
|
'url' => '...',
|
|
],
|
|
],
|
|
|
|
'source_refs' => [
|
|
['type' => 'environment_review', 'id' => 6],
|
|
['type' => 'review_pack', 'id' => 8],
|
|
],
|
|
|
|
'evidence_refs' => [
|
|
['type' => 'evidence_snapshot', 'id' => 8],
|
|
],
|
|
|
|
'technical_details' => [
|
|
'review_status' => 'published',
|
|
'output_readiness' => 'publication_blocked',
|
|
'evidence_state' => 'missing',
|
|
],
|
|
]
|
|
```
|
|
|
|
## Required Fields
|
|
|
|
| Field | Requirement |
|
|
|---|---|
|
|
| `key` | Stable, repo-owned case identifier |
|
|
| `scope` | Explicit workspace/environment/review/operation/provider scope |
|
|
| `severity` | Presentation-only severity |
|
|
| `status` | Presentation-only actionability state |
|
|
| `title` | Primary operator-facing issue label |
|
|
| `reason` | Plain-language explanation of the dominant cause |
|
|
| `impact` | Why this matters now |
|
|
| `primary_action` | Exactly one dominant next step |
|
|
| `secondary_actions` | Optional supporting navigation/disclosure actions |
|
|
| `source_refs` | Required repo-backed source references |
|
|
| `evidence_refs` | Optional but required when evidence truth is central to the case |
|
|
| `technical_details` | Secondary disclosure payload only |
|
|
|
|
## Allowed Scope Types
|
|
|
|
- `workspace`
|
|
- `environment`
|
|
- `review`
|
|
- `review_pack`
|
|
- `evidence`
|
|
- `provider_connection`
|
|
- `operation`
|
|
- `finding`
|
|
- `system`
|
|
|
|
## Allowed Severities
|
|
|
|
- `critical`
|
|
- `warning`
|
|
- `info`
|
|
- `success`
|
|
|
|
## Allowed Statuses
|
|
|
|
- `action_required`
|
|
- `blocked`
|
|
- `needs_review`
|
|
- `informational`
|
|
- `ready`
|
|
- `resolved`
|
|
- `unknown`
|
|
|
|
## Existing Runtime Inputs To Reuse
|
|
|
|
| Existing producer | How it maps into `ResolutionCase` |
|
|
|---|---|
|
|
| `ReviewPackOutputResolutionGuidance` | `title`, `reason`, `impact`, `primary_action`, `secondary_actions`, `technical_details`, and review-output evidence-basis truth |
|
|
| `OperationUxPresenter` | dominant issue/action text for operation follow-up cases |
|
|
| `OperatorExplanationPattern` | trust/reliability/next-action semantics that can inform title/reason/impact |
|
|
| `EnterpriseDetailSectionFactory::primaryNextStep()` | existing primary-next-step shape for action text and supporting guidance |
|
|
| provider readiness summaries and required-permissions guidance | provider-owned issue/reason/action sources |
|
|
|
|
## Hard Rules
|
|
|
|
- Do not persist resolution cases.
|
|
- Do not create source refs that cannot be resolved to repo-backed records.
|
|
- Do not expose more than one primary action.
|
|
- Do not encode hidden scope.
|
|
- Do not force executable action metadata onto producers that only support navigation, qualified download, or disclosure today.
|
|
- Do not introduce a standalone evidence-basis adapter in v1 while review-output guidance already owns that truth.
|
|
- Do not use the contract as a generic workflow-state machine.
|