TenantAtlas/specs/350-operator-resolution-guidance-framework-v1/repo-truth-map.md

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