ahmido 4cf2712f92 feat: operator resolution guidance framework v1 (spec 350) (#421 )

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

2026-06-03 15:35:25 +00:00

4.5 KiB

Raw Permalink Blame History

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:

What is wrong?
Why does it matter?
What is the dominant next step?
Is that step navigation/disclosure-only or an existing safe executable path?
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

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

4.5 KiB Raw Permalink Blame History