TenantAtlas/specs/353-provider-connections-resolution-guidance-v1/repo-truth-map.md

Repo Truth Map: Spec 353 - Provider Connections Resolution Guidance v1

Status: draft / prep-ready
Branch: 353-provider-connections-resolution-guidance-v1
Date: 2026-06-04
Baseline commit before prep branch: 9a564d6b (feat: environment dashboard operator guidance consolidation (spec 352) (#423))

Branch And Working-Tree Safety

• Starting branch before prep: platform-dev
• Initial git status --short --branch: clean
• Initial git diff --stat: empty
• Spec Kit branch created via repo script:
  • ./.specify/extensions/git/scripts/bash/create-new-feature.sh --json --short-name 'provider-connections-resolution-guidance-v1' --number 353 'Provider Connections Resolution Guidance v1'
• Current branch after setup: 353-provider-connections-resolution-guidance-v1
• Current uncommitted change before writing prep artifacts: only specs/353-provider-connections-resolution-guidance-v1/

Why 353 Was Selected

• Spec 352 intentionally made provider blockers the dominant Environment Dashboard guidance case.
• The dashboard now links operators into Provider Connections / Required Permissions, but those destination surfaces still read diagnostics-first.
• Provider readiness is already called out as a grouped P1 follow-up in:
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/target-experience-briefs/provider-readiness.md
• The slice is small and repo-ready because the current repo already has the necessary underlying truth:
  • provider connection status fields
  • permission counts and capability groups
  • verification runs and proof links
  • dashboard operator guidance precedence

Why Close Alternatives Were Deferred

• Governance Inbox follow-through is already farther along in the current spec sequence and is not the blocker named by the user for this prep.
• Customer-facing localization is still valuable but does not close the provider-blocker destination gap opened by Spec 352.
• Broader onboarding/provider redesign would be too large for the current narrow follow-up slice.

Completed-Spec Guardrail Result

Related spec	Current signal	Handling for Spec 353
Spec 338	checked implementation tasks and browser-smoke history	completed baseline; do not reopen scope contracts
Spec 339	checked implementation tasks over provider scope hardening	completed baseline; reuse scope rules only
Spec 350	shared guidance framework and contract artifacts already exist	context only; reuse, do not reopen
Spec 351	repo-real review-output action semantics with residual browser notes	reuse shared guidance lessons only; do not hide residual notes
Spec 352	repo-truth-map.md says Status: implemented	immediate dependency; follow dashboard target continuity only

No specs/353-* package or 353-* branch existed before this prep.

Runtime Seam Inventory

Surface / seam	Repo-real path(s)	Notes
Provider Connections list	apps/platform/app/Filament/Resources/ProviderConnectionResource.php, Pages/ListProviderConnections.php	Table already shows consent, verification, provider capability, last check, and current environment filter behavior
Provider Connections view	apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ViewProviderConnection.php	Already exposes primary Grant admin consent CTA and grouped secondary actions
Provider Connections edit	apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/EditProviderConnection.php	Already exposes View last check run plus existing provider operations
Required Permissions page	apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php, apps/platform/resources/views/filament/pages/environment-required-permissions.blade.php	Already has summary, guidance copy, issue cards, copy payloads, and technical-details disclosure
Permission posture builder	apps/platform/app/Services/Intune/ManagedEnvironmentRequiredPermissionsViewModelBuilder.php	Already derives overall status, counts, capability groups, feature impacts, and freshness
Provider readiness summary	apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php	Already derives consent state, verification state, readiness summary, and primary provider capability
Provider blocker translation	apps/platform/app/Support/Providers/ProviderReasonTranslator.php, apps/platform/app/Support/Verification/VerificationLinkBehavior.php	Already translates reason codes and classifies required-permissions / provider-connections paths as internal diagnostic targets
Dashboard provider blocker	apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php	Already promotes required_permissions / delegated_permissions into provider operatorGuidance
Onboarding/provider state helper	apps/platform/app/Filament/Resources/ManagedEnvironmentResource.php	Already has providerConnectionState() and related provider-state presentation helpers

Draft-To-Repo Deviations That Must Stay Explicit

User draft assumption	Repo truth	Spec 353 handling
EnvironmentProviderHealth.php exists	no such page class exists	do not invent it; use existing provider readiness helpers
ui-077-required-permissions.md already exists	no file currently exists	create it during implementation instead of claiming an update
Provider Connections still needs a primary CTA	view page already has Grant admin consent	guidance must coexist with the existing safe CTA hierarchy
Required Permissions is mostly a raw list	page already has summary, issue cards, and technical details	productize current page instead of rebuilding it
Dashboard still needs provider priority work	provider blockers already outrank review-output in Spec 352	focus on destination continuity, not a new dashboard ranking spec

Likely Implementation Files

• apps/platform/app/Filament/Resources/ProviderConnectionResource.php
• apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php
• apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ViewProviderConnection.php
• apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/EditProviderConnection.php
• apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php
• apps/platform/resources/views/filament/pages/environment-required-permissions.blade.php
• bounded provider-guidance support class under apps/platform/app/Support/... only if needed
• apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php only if continuity needs a narrow adjustment
• docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md
• docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md

Files Explicitly Out Of Scope

• provider API adapters and Graph clients
• onboarding workflow internals beyond existing outbound links
• migrations, tables, enums, or new persisted readiness truth
• customer portal, PDF/HTML renderer, PSA, billing, or AI follow-up files

Prep Conclusion

Spec 353 is repo-safe as a new prep target:

• the selected candidate is not already prepared as 353-*
• the dependency chain is explicit
• the needed runtime truth already exists
• the remaining work is a bounded productization/guidance layer, not a provider architecture rewrite