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