TenantAtlas/specs/281-provider-connection-scope/quickstart.md

Quickstart: Provider Connection Scope & Microsoft Profile Extraction

Reviewer Flow

1. Read spec.md, plan.md, research.md, and data-model.md together.
2. Confirm the package stays on reserved slot 281 only and treats Spec 279 as completed context and Spec 280 as adjacent prepared routing work only.
3. Confirm the verified current repo truth: ProviderConnection already uses managed_environment_id, ProviderConnectionResource is already non-globally-searchable with Create, View, and Edit pages, and config/provider_boundaries.php already classifies provider.connection_resolution, provider.identity_resolution, and provider.operation_start_gate as platform-core seams.
4. Confirm the package does not introduce a provider-profile table, registry, capability engine, or any other speculative multi-provider framework.
5. Confirm the canonical shared target-scope contract is explicit and unchanged across artifacts: provider, scope_kind, scope_identifier, scope_display_name, shared_label, and shared_help_text.
6. Confirm the shared identity-result contract is explicit and neutral: target scope, effective client identity, credential source, blocked reason, and nested provider-context details; shared tenantContext is not treated as the long-term platform-core field name.
7. Confirm the planned OperationRun context rewrite is explicit: shared target_scope becomes the neutral descriptor shape and provider-specific Microsoft detail moves to nested provider context or profile metadata rather than staying at target_scope.entra_tenant_id.
8. Confirm ProviderConnectionSurfaceSummary remains the single summary contract for ProviderConnectionResource, ManagedTenantOnboardingWizard, and managed-environment related-context provider summaries.
9. Confirm Filament guardrails remain explicit: Filament v5 stays on Livewire v4, provider registration stays in apps/platform/bootstrap/providers.php, ProviderConnectionResource stays non-globally-searchable, destructive provider-connection mutations stay confirmation-protected and server-authorized, and asset strategy remains unchanged.
10. Confirm no application implementation, test execution, or non-spec artifact modification is included in this prep package.

Planned Validation Commands

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Feature/Providers/ProviderConnectionTargetScopeNeutralityTest.php tests/Feature/Providers/ProviderIdentityResolutionNeutralityTest.php tests/Feature/Providers/ProviderOperationStartGateTargetScopeContextTest.php tests/Feature/Filament/ProviderConnectionResourceScopeSummaryTest.php tests/Feature/Onboarding/ManagedTenantOnboardingProviderConnectionScopeTest.php tests/Feature/Guards/ProviderConnectionMicrosoftScopeLeakGuardTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail artisan test --compact tests/Browser/Spec281ProviderConnectionScopeSmokeTest.php)

export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && REPO_ROOT="$(git rev-parse --show-toplevel)" && (cd "$REPO_ROOT/apps/platform" && ./vendor/bin/sail bin pint --dirty --format agent)

Review Questions

• Does the package stay bounded to contract extraction across the current provider seams rather than drifting into a provider framework or profile table?
• Does the package explicitly avoid reintroducing the stale provider_connections.tenant_id move?
• Does the shared target_scope schema stay neutral everywhere in the package instead of carrying entra_tenant_id as shared truth?
• Does the identity-result contract make effective client identity and credential source explicit while keeping provider-specific Microsoft detail nested?
• Do provider-connections, onboarding, and related-context summaries all reuse one shared summary adapter?
• Does the start-gate contract clearly replace shared target_scope.entra_tenant_id with a neutral target_scope object plus nested provider context?
• Does ProviderConnectionResource stay non-globally-searchable while preserving View and Edit page destinations and the current confirmation-protected actions?
• Does the package keep Filament on Livewire v4, keep provider registration in apps/platform/bootstrap/providers.php, and avoid new asset or deployment steps?
• Do Specs 282 through 287 remain explicitly deferred rather than silently absorbed?

Notes

• This prep package changes only planning artifacts under specs/281-provider-connection-scope/.
• No application implementation, tests, or runtime validation were executed while preparing the package.