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
80 lines
2.6 KiB
Markdown
80 lines
2.6 KiB
Markdown
# Adapter Contract
|
|
|
|
Status: Draft for Spec 350
|
|
Scope: Runtime adapters that wrap existing guidance-producing truth
|
|
|
|
## Purpose
|
|
|
|
Each adapter translates one current repo-real guidance family into one or more `ResolutionCase` objects without inventing a new workflow system.
|
|
|
|
Adapters are not source-of-truth owners. They are normalizers over existing truth.
|
|
|
|
## Required Responsibilities
|
|
|
|
Each adapter must:
|
|
|
|
1. accept already-scoped repo-backed input
|
|
2. determine the dominant issue case
|
|
3. derive one primary action
|
|
4. attach source refs and evidence refs where applicable
|
|
5. attach technical details as secondary disclosure only
|
|
6. preserve existing action safety requirements
|
|
|
|
Each adapter must not:
|
|
|
|
1. persist new state
|
|
2. create new domain lifecycle or workflow state
|
|
3. perform remote calls during render
|
|
4. invent actions that do not exist safely in the repo
|
|
|
|
## Suggested Adapter Inputs
|
|
|
|
| Adapter | Expected input truth |
|
|
|---|---|
|
|
| `ReviewPackOutputResolutionAdapter` | `EnvironmentReview`, `ReviewPack`, `EvidenceSnapshot`, existing output-readiness guidance |
|
|
| standalone evidence-basis adapter | not justified in v1 because evidence-basis truth is already part of review-output guidance |
|
|
| `ProviderReadinessResolutionAdapter` | existing provider surface summary, required-permissions guidance, verification truth |
|
|
| `OperationFollowUpResolutionAdapter` | existing `OperationRun`, `OperationUxPresenter`, operator explanation, proof links |
|
|
|
|
## Output Rule
|
|
|
|
Each adapter returns either:
|
|
|
|
- one dominant `ResolutionCase`, or
|
|
- a small ordered list of cases where the consumer surface can legitimately display more than one case without creating a warning wall
|
|
|
|
Default bias: one dominant case.
|
|
|
|
## Consumer Rule
|
|
|
|
Consumer surfaces may:
|
|
|
|
- render one case card
|
|
- render a bounded list
|
|
- merge case metadata into an existing first-viewport decision block
|
|
|
|
Consumer surfaces may not:
|
|
|
|
- rebuild the adapter logic locally
|
|
- fork the primary-action logic without documenting why
|
|
- elevate technical details above the dominant case
|
|
|
|
## V1 Required Adapters
|
|
|
|
- `ReviewPackOutputResolutionAdapter`
|
|
|
|
## Optional Same-Slice Adapters
|
|
|
|
- `ProviderReadinessResolutionAdapter`
|
|
- `OperationFollowUpResolutionAdapter`
|
|
|
|
These adapters are allowed only when a concrete in-scope consumer can adopt them without a broader surface redesign.
|
|
|
|
## Optional Later Adapters
|
|
|
|
- `FindingRequiresTriageResolutionAdapter`
|
|
- `AcceptedRiskReviewResolutionAdapter`
|
|
- standalone evidence-basis adapter after a non-review consumer proves it is necessary
|
|
|
|
Those optional adapters are out of current guaranteed scope unless the implementation proves they can be added without widening the feature.
|