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