02cc12f73f
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 59s
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.
69 lines
6.1 KiB
Markdown
69 lines
6.1 KiB
Markdown
# Spec 350 - Repo Truth Map
|
|
|
|
Created: 2026-06-03
|
|
Scope: Operator Resolution Guidance Framework v1
|
|
|
|
This map records the repo-backed truth that Spec 350 is allowed to standardize. It exists to stop the implementation from inventing a workflow engine or a second explanation subsystem.
|
|
|
|
## Existing Guidance Producers
|
|
|
|
| Area | Repo evidence | Current repo-real truth | Current gap | Spec 350 handling |
|
|
|---|---|---|---|---|
|
|
| Review output guidance | `apps/platform/app/Support/ReviewPacks/ReviewPackOutputResolutionGuidance.php` | Derived review/output guidance already exists with state, reason, impact, one primary action, secondary actions, technical details, and evidence-basis semantics | local to review-output path; no shared source/scope/action envelope | required adapter; wrap, do not replace |
|
|
| Customer-safe review consumer | `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php` | first-screen review output uses existing output guidance plus repo-real findings and accepted-risk follow-up overrides | page-local contract and helper structure | first required visible consumer; preserve overrides |
|
|
| Review detail consumer | `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php` | detail surface already exposes output guidance and qualified download wording, and customer-workspace detail mode suppresses repeated action rails | not yet expressed as a shared case contract | second required visible consumer; preserve detail-mode suppression |
|
|
| Operation follow-up | `apps/platform/app/Support/OpsUx/OperationUxPresenter.php` | dominant follow-up text already exists for runs | mostly text-only; no explicit case/action/source envelope | optional bounded adapter only if an in-scope consumer needs it |
|
|
| Shared explanation | `apps/platform/app/Support/Ui/OperatorExplanation/OperatorExplanationPattern.php` | operator explanation already separates trust/reliability/next action for some domains | not a cross-domain resolution-case envelope | reuse as semantic input |
|
|
| Shared next-step shape | `apps/platform/app/Support/Ui/EnterpriseDetail/EnterpriseDetailSectionFactory.php` | `primaryNextStep()` already models main text + secondary guidance | local to enterprise-detail surfaces | reuse as action-shape prior art |
|
|
| Governance Inbox | `apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php` | page already shows `Next recommended action` over lane-specific items | queue-specific, not reusable across other domains | optional bounded consumer |
|
|
| Provider readiness | `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php` | readiness summary already exists for provider connections | no shared action-safe case envelope | optional adapter input only |
|
|
| Required permissions guidance | `apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php` | page already exposes guidance, verification link, and provider-management link | local guidance page, not shared case contract | optional bounded consumer |
|
|
| Environment dashboard recommendations | `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php` | readiness and recommended-action summaries already exist | dashboard-local action model | optional bounded consumer |
|
|
|
|
## Existing Shared Contracts To Reuse
|
|
|
|
| Contract / helper | What it already solves | Spec 350 rule |
|
|
|---|---|---|
|
|
| `ReviewPackOutputResolutionGuidance` | issue + reason + impact + one action for review output | do not re-derive raw output truth |
|
|
| `OperationUxPresenter::surfaceGuidance()` | dominant follow-up text for run states | do not replace run lifecycle or toasts/notifications |
|
|
| `OperatorExplanationPattern` | trust/reliability/next-action semantics | use as semantic input, not duplicate terminology |
|
|
| `EnterpriseDetailSectionFactory::primaryNextStep()` | existing primary-next-step structure | align action naming and supporting guidance |
|
|
| `OperationRunLinks` and existing scoped URL helpers | safe deep-linking | reuse for all action destinations |
|
|
|
|
## Verified Scope Constraints
|
|
|
|
- No new persistence is justified by current repo truth.
|
|
- No new route family is justified.
|
|
- No new workflow engine is justified.
|
|
- No hidden shell/sidebar/topbar scope is allowed.
|
|
- Provider-specific language must remain bounded to provider-owned adapters and surfaces.
|
|
- Any executable action must defer to existing capability, confirmation, audit, and `OperationRun` paths.
|
|
|
|
## Known Overlap / Drift Risks
|
|
|
|
1. `ReviewPackOutputResolutionGuidance` already looks like a case contract for one domain; Spec 350 must wrap it, not supersede it.
|
|
2. `CustomerReviewWorkspace` already overrides review-output guidance for findings and accepted-risk follow-up; Spec 350 must preserve those repo-real exceptions instead of flattening them away.
|
|
3. `EnvironmentReviewResource` already suppresses repeated action rails in customer-workspace detail mode; Spec 350 must preserve that behavior.
|
|
4. `OperatorExplanationPattern` already exists for another domain family; Spec 350 must not become a competing explanation framework.
|
|
5. Governance Inbox and environment dashboard already have local next-action logic; if integrating them would require a bigger taxonomy rewrite, they stay out of scope.
|
|
6. A standalone evidence-basis adapter is not justified in v1 because the review-output path already carries evidence-basis truth through `ReviewPackOutputResolutionGuidance`.
|
|
7. Spec 347 contains a speculative follow-up note using number `350`; this is commentary only and not a real package reservation.
|
|
|
|
## Narrowest Correct Implementation Boundary
|
|
|
|
The current repo truth supports:
|
|
|
|
- one shared derived case/action envelope
|
|
- one required review-output adapter over existing guidance producers
|
|
- two required visible consumers on the review-output path
|
|
- optional provider-readiness or operation-follow-up adapters only when a concrete same-slice consumer keeps the reuse cost low
|
|
- optional additional consumers only when the reuse cost stays low
|
|
|
|
The current repo truth does not support:
|
|
|
|
- a generic workflow engine
|
|
- a new provider-neutral execution framework
|
|
- a new persisted resolution queue
|
|
- a mandatory standalone evidence-basis adapter in v1
|
|
- a broad dashboard or governance surface redesign hidden inside this spec
|