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

Feature Specification: Provider Connection, Provider Scope & Microsoft Profile Extraction

Feature Branch: 281-provider-connection-scope
Created: 2026-05-07
Status: Ready
Input: User description: "Work only in /Users/ahmeddarrazi/Documents/projects/wt-plattform on the already-created feature branch 281-provider-connection-scope. This is preparation-only work. Do not modify application/runtime code, tests, migrations, models, routes, views, or any non-spec artifacts.

Task: fill /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/281-provider-connection-scope/spec.md as the implementation-ready spec for candidate 281 - Provider Connection, Provider Scope & Microsoft Profile Extraction from docs/product/spec-candidates.md and docs/product/roadmap.md.

Required repo truth and constraints:

• Use the existing style and depth of specs/280-workspace-tenancy-environment-routing/spec.md.
• Current branch/worktree safety is already checked and safe; stay on 281-provider-connection-scope.
• 279 is completed historical context; 280 is an active/prepared adjacent spec but not the target. Do not edit any existing completed or adjacent spec packages.
• The raw candidate text is partially stale: provider_connections already use managed_environment_id in repo truth, so do not claim 281 still needs the tenant_id -> managed_environment_id move. Document that as a candidate deviation.
• Current repo seams show the real remaining 281 work lives around:
  • apps/platform/app/Models/ProviderConnection.php
  • apps/platform/config/provider_boundaries.php
  • apps/platform/app/Services/Providers/ProviderConnectionResolver.php
  • apps/platform/app/Services/Providers/ProviderIdentityResolver.php
  • apps/platform/app/Services/Providers/ProviderIdentityResolution.php
  • apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php
  • apps/platform/app/Services/Providers/ProviderOperationStartGate.php
  • apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php
  • apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeDescriptor.php
  • apps/platform/app/Services/Providers/CredentialManager.php
• Repo truth currently still hardcodes Microsoft-shaped identity/scope in platform-core seams via ProviderConnection::entra_tenant_id, tenantContext strings, and OperationRun context target_scope.entra_tenant_id.
• There is already provider-boundary groundwork and target-scope normalization, but no dedicated provider-profile model/table yet.
• Follow constitution rules: prefer bounded extraction over speculative multi-provider frameworks; no new persisted truth unless justified; provider-owned vs platform-core seams must be classified explicitly.
• Keep the spec narrow and implementation-ready. Prefer the smallest honest slice that normalizes provider-neutral target-scope and identity contracts while confining Microsoft-specific profile semantics to provider-owned metadata/profile seams.
• Preserve TenantPilot terminology where the repo still uses it, but make the platform-core/provider-boundary reasoning explicit.
• Include the mandatory spec-template sections, candidate gate summary, completed-spec guardrail result, assumptions, risks, in-scope/non-goals, and deferred adjacent candidates.
• Include explicit Candidate Selection Gate reasoning for why 281 is chosen now and why 282-287 are deferred.
• Include the explicit agent-output contract details relevant at spec level: Livewire v4 compliance note, provider registration location bootstrap/providers.php, globally searchable resource note if any touched resource is mentioned, destructive action confirmation note if any UI mutation is referenced, asset strategy note, testing plan summary.
• Make the final spec concrete enough that a later plan/tasks pass can generate research/data-model/quickstart/contracts without guesswork."

Spec Candidate Check

• Problem: Repo truth already moved ProviderConnection onto managed_environment_id, but shared platform-core seams still treat Microsoft tenant identity as the generic provider-scope truth. ProviderIdentityResolver, ProviderIdentityResolution, PlatformProviderIdentityResolver, ProviderConnectionTargetScopeNormalizer, ProviderOperationStartGate, and related operator summaries still lean on entra_tenant_id, tenantContext, and target_scope.entra_tenant_id as if they were neutral platform contracts.
• Today's failure: Operators can reach provider connections and start provider-backed work, but the shared connection identity story still depends on Microsoft-shaped field names. Onboarding readiness, provider connection summaries, audit metadata, and OperationRun context can all describe the same connection differently, which makes the cutover pack look provider-neutral in naming while still being Microsoft-shaped in the seams that actually decide behavior.
• User-visible improvement: Operators get one consistent provider-connection and target-scope story across provider connections, managed-environment detail summaries, onboarding readiness, and provider-operation follow-up. Microsoft consent, portal, and tenant-profile details remain available, but only inside clearly provider-owned profile/context disclosure instead of as the primary shared vocabulary.
• Smallest enterprise-capable version: Reuse the current ProviderConnection record, ProviderConnectionResource, onboarding wizard, target-scope normalizer, identity resolution path, and provider-operation start gate; standardize provider-neutral target-scope and identity outputs across those seams; move Microsoft-specific profile semantics into provider-owned metadata/profile sections; and stop writing target_scope.entra_tenant_id as the shared run-context contract. No new table, registry, package engine, or multi-provider framework is introduced.
• Explicit non-goals: No tenant_id -> managed_environment_id migration on provider_connections; no dedicated provider-profile table; no capability registry; no provider-neutral artifact taxonomy; no governance-artifact retargeting; no workspace-RBAC redesign; no broader copy/localization neutralization; no new provider implementation; no legacy fallback or backfill.
• Permanent complexity imported: One refined provider-neutral target-scope and identity contract across existing seams, one provider-owned Microsoft profile disclosure pattern on existing surfaces, and focused feature/browser coverage. No new persisted truth, registry, or extension framework is added.
• Why now: Spec 279 already completed the core managed-environment noun change, and Spec 280 prepares the workspace-first routing shell. The next verified blocker in the reserved cutover pack is the provider boundary itself: until 281 lands, later slices such as artifact retargeting and provider-neutral taxonomy would still inherit Microsoft-shaped shared connection and run context.
• Why not local: A label-only or page-local fix would leave the deciding seams untouched. ProviderConnectionResolver, ProviderIdentityResolver, ProviderIdentityResolution, PlatformProviderIdentityResolver, ProviderOperationStartGate, and audit/run context are the real control points; if they stay Microsoft-shaped, the platform core remains Microsoft-shaped no matter how neutral the page copy becomes.
• Approval class: Core Enterprise
• Red flags triggered: Shared provider/platform boundary, provider-operation execution context, and temptation to introduce new persistence or a speculative provider framework. Defense: this slice explicitly rejects a new table, registry, or capability framework and instead reuses the existing target-scope, identity, resource, and onboarding seams as the narrowest current-release extraction path.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 1 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 10/12
• Decision: approve

Spec Scope Fields

• Scope: workspace
• Primary Routes:
  • /admin/provider-connections
  • /admin/provider-connections/create with managed_environment_id query context
  • /admin/provider-connections/{record}
  • /admin/provider-connections/{record}/edit
  • named onboarding routes admin.onboarding and admin.onboarding.draft
  • managed-environment detail and related-context entry points that deep-link into provider connections under the surviving admin panel
• Data Ownership:
  • ProviderConnection remains the existing workspace-owned, managed-environment-scoped provider binding record
  • ProviderCredential remains the existing provider-owned secret record attached to one ProviderConnection
  • Microsoft-specific profile semantics remain provider-owned metadata/profile detail; this slice does not introduce a dedicated provider-profile table or other new persisted truth
  • OperationRun remains execution truth and records provider-neutral target-scope fields plus provider-specific nested context only where provider-specific follow-up truly needs it
• RBAC:
  • workspace membership remains the first isolation boundary
  • managed-environment access remains the second isolation boundary
  • PROVIDER_VIEW, PROVIDER_MANAGE, PROVIDER_MANAGE_DEDICATED, and PROVIDER_RUN remain the capability gates for the existing provider-connection surfaces
  • non-members stay 404, and in-scope actors missing a capability stay 403

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes
• Interaction class(es): navigation entry points, list/detail summaries, onboarding readiness messaging, provider-operation start feedback, audit metadata, and provider-specific consent/navigation links
• Systems touched: ProviderConnectionResource, ProviderConnectionSurfaceSummary, TenantResource related-context/provider summary entries, ManagedTenantOnboardingWizard, ProviderConnectionResolver, ProviderIdentityResolver, ProviderIdentityResolution, PlatformProviderIdentityResolver, ProviderOperationStartGate, ProviderConnectionTargetScopeNormalizer, ProviderConnectionTargetScopeDescriptor, CredentialManager, RequiredPermissionsLinks, AdminConsentUrlFactory, and config/provider_boundaries.php
• Existing pattern(s) to extend: the current target-scope descriptor/normalizer path, the current provider-connection resource action family, the current onboarding readiness/provider summary path, and the shared provider-operation start gate/presenter contract
• Shared contract / presenter / builder / renderer to reuse: ProviderConnectionTargetScopeDescriptor, ProviderConnectionTargetScopeNormalizer, ProviderIdentityResolution, ProviderConnectionSurfaceSummary, ProviderOperationStartGate, ProviderOperationStartResultPresenter, and the existing ProviderConnectionResource action group/view model helpers
• Why the existing shared path is sufficient or insufficient: the repo already has the right shared seams. What is insufficient is not the absence of a framework, but the Microsoft-shaped payload and naming that still flows through those seams. Extending the existing path is sufficient; creating a new provider framework is not.
• Allowed deviation and why: one bounded deviation is allowed: Microsoft-specific tenant-profile, consent, portal, and required-permissions details may remain inside a clearly provider-owned profile/context block or nested provider metadata where current support and consent workflows need them. They must not become the shared label set for target scope, provider identity, or run context.
• Consistency impact: provider-connection list/detail pages, managed-environment summaries, onboarding readiness, audit metadata, and provider-operation follow-up must all describe the same connection with the same shared target-scope summary before any provider-specific detail is shown.
• Review focus: reviewers must verify that the shared target-scope/identity contract is reused instead of a parallel helper, that Microsoft detail is nested inside provider-owned sections only, that the provider-connection resource and onboarding wizard show the same summary contract, and that no new table or registry quietly appears.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, start/block/link semantics only
• Shared OperationRun UX contract/layer reused: ProviderOperationStartGate, ProviderOperationStartResultPresenter, OperationUxPresenter, OperationRunLinks, and the existing OperationRunService lifecycle path
• Delegated start/completion UX behaviors: current shared start-gate and presenter paths remain responsible for queued/block/dedupe messaging, run links, and lifecycle semantics; this slice only changes the connection identity and target-scope data they carry
• Local surface-owned behavior that remains: ProviderConnectionResource and ManagedTenantOnboardingWizard continue to own only initiation inputs, connection selection, and current-surface follow-up links
• Queued DB-notification policy: N/A - unchanged shared policy
• Terminal notification path: existing central lifecycle mechanism
• Exception required?: none

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected:
  • platform-core: provider.connection_resolution, provider.identity_resolution, provider.operation_start_gate
  • provider-owned: Microsoft consent URL shaping, Microsoft portal/profile details, and Microsoft Graph runtime option mapping
  • mixed UI bridge: provider-connection summaries, managed-environment related context, and onboarding readiness that expose shared target-scope truth plus provider-specific follow-up detail
• Neutral platform terms preserved or introduced: provider connection, target scope, scope kind, scope identifier, scope display name, effective client identity, credential source, provider profile, provider context, workspace, and managed environment
• Provider-specific semantics retained and why: Microsoft tenant directory ID, authority tenant, admin-consent callback/URL, required-permissions guidance, Graph client identity, domains, and portal links remain necessary for current consent and troubleshooting workflows. They stay provider-owned and must not be promoted into platform-core truth.
• Why this does not deepen provider coupling accidentally: shared platform-core seams move toward neutral target_scope and identity language, while Microsoft-specific profile detail is explicitly nested under provider-owned metadata/profile seams. The feature removes a Microsoft-shaped hotspot instead of creating a new generalized provider platform.
• Follow-up path: Spec 282 for governance-artifact retargeting consumers, Spec 283 for capability registry follow-through, Spec 284 for provider-neutral artifact taxonomy, Spec 285 for workspace-first RBAC follow-through, Spec 286 for broader operator-copy neutralization, and Spec 287 for the cutover quality-gate pack

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Provider connections resource family (List, View, Create, Edit)	yes	Native Filament resource plus shared action/presenter primitives	list/detail summary, consent/action group, provider-operation feedback	page, table, detail, modal, Livewire state	no	Reuses the existing resource, action surface declaration, and view/edit pages; the slice changes shared connection/profile semantics, not the route family
Managed-environment detail provider connection summary and related-context entry	yes	Native Filament resource detail plus existing related-context pattern	related navigation, summary chips, environment-scoped follow-up	detail, link state	no	Summary only; no new detail surface or action family is introduced
Managed-environment onboarding provider-connection step	yes	Native Filament custom wizard using existing onboarding shell and shared provider summaries	workflow selection, readiness summary, supporting links	page, wizard, session, Livewire state	no	Reuses the onboarding wizard; no second onboarding framework or connection picker is introduced

Decision-First Surface Role

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Provider connections resource family	Primary Decision Surface	Operator decides whether one provider connection is usable, default-worthy, or ready to run provider work	managed environment, provider, target scope, lifecycle, consent, verification	credential source, migration-review detail, provider-specific profile data, last error, and run follow-up	Primary because this is the configuration and execution surface where the operator chooses the active provider binding	Matches the existing integrations/settings workflow instead of inventing another workbench	Removes the need to jump between tenant detail, onboarding, and operations just to identify connection scope
Managed-environment detail provider connection summary and related-context entry	Secondary Context Surface	Operator confirms an environment has a usable provider connection and decides whether to drill in	high-level provider-connection summary and direct link	full connection detail remains on the provider-connections resource	Secondary because it advertises context and next step rather than owning the decision itself	Keeps managed-environment overview calm while still exposing the next relevant integration step	Reduces navigation search and duplicate summary cards
Managed-environment onboarding provider-connection step	Primary Decision Surface	Operator chooses or creates the connection that will unblock onboarding readiness	selected connection, target scope summary, consent/readiness state, next step	provider-specific profile detail, verification detail, and supporting links	Primary because onboarding cannot continue safely until the correct connection is chosen and understood	Matches the current onboarding workflow and keeps connection readiness inside it	Prevents operators from reconstructing connection identity from raw IDs or separate pages

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Provider connections resource family	operator-MSP, support-platform	provider, target scope, lifecycle, consent, verification, and current default-connection truth	credential source, migration review, blocked reason, recent operation follow-up	Microsoft-specific profile identifiers, portal links, required-permissions detail, and other provider-owned troubleshooting context	Open, Check connection, or one existing primary provider action depending on surface	dedicated credential secrets, provider-owned raw detail, and support-only context stay gated or nested	target scope is stated once in the shared summary and not re-explained in every provider-specific subsection
Managed-environment detail provider connection summary and related-context entry	operator-MSP, support-platform	whether a connection exists, its high-level status, and where to go next	minimal summary only	none on this surface	Open provider connections	provider-specific profile detail stays on the provider-connections resource	the managed-environment page advertises the next step without duplicating the full connection detail card
Managed-environment onboarding provider-connection step	operator-MSP, support-platform	selected connection, target scope summary, consent/readiness status, and the next unblock action	verification result, blocked reason, supporting links, and run continuity	provider-specific profile detail stays behind provider-owned disclosure or support links	Select connection, Create connection, or Continue depending on current state	raw provider profile detail and credential data stay hidden	the wizard uses the same target-scope summary as the resource instead of inventing a second identity story

UI/UX Surface Classification

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Provider connections resource family	List / Detail / Integrations	CRUD / List-first Resource	Open one connection, verify it, or run provider work	clickable row to the View page	required	grouped under More on list/view surfaces	grouped under More, server-authorized, confirmation-required where mutating or dangerous	/admin/provider-connections	/admin/provider-connections/{record} and /admin/provider-connections/{record}/edit	managed-environment filter, workspace context, provider, target scope	Provider connection	target scope and connection health	none
Managed-environment detail provider connection summary and related-context entry	Detail / Related Context / Navigation	Environment detail follow-up entry	Open provider connections for the current managed environment	explicit related-context Open link	forbidden	none beyond the explicit open affordance	none	managed-environment detail surface with provider-connections deep link	/admin/provider-connections?managed_environment_id={environment}	current workspace and current managed environment	Provider connections	whether the environment is wired to a usable provider connection	none
Managed-environment onboarding provider-connection step	Workflow Hub / Wizard / Readiness	Workflow-step selector	Select or create the correct provider connection and continue onboarding	in-step selection and explicit create or manage actions	forbidden	supporting links and provider follow-up remain secondary	none added by this slice	named onboarding routes admin.onboarding and admin.onboarding.draft	same wizard step or draft route	current workspace, current managed environment, selected provider connection	Provider connection	selected connection and readiness state	none

Operator Surface Contract

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Provider connections resource family	Workspace operator	Decide whether one provider connection is the right and healthy binding for this managed environment	List/detail resource	Is this the right provider connection and is it safe to use right now?	managed environment, provider, target scope, lifecycle, consent, verification, default state	migration review, last error, credential source, provider-specific profile detail, run follow-up	lifecycle, consent, verification, migration-review	TenantPilot only for connection metadata and credentials, Microsoft tenant only when admin consent or provider execution is triggered	Open, Check connection, Inventory sync, Compliance snapshot, Edit	Set default, enable or rotate dedicated credentials, revert or delete credentials, enable or disable connection
Managed-environment detail provider connection summary and related-context entry	Workspace operator	Decide whether to inspect or fix provider connection state from the environment overview	Related-context summary	Do I need to drill into provider connections from this environment now?	high-level connection presence and status plus direct link	none beyond brief summary copy	lifecycle, verification	none	Open provider connections	none
Managed-environment onboarding provider-connection step	Workspace operator	Choose the connection that will unblock onboarding and later provider operations	Wizard step	Which provider connection should this onboarding flow use, and is it ready?	selected connection, target scope summary, readiness and consent state, next step	blocked reason, supporting verification links, provider-specific profile detail on demand	readiness, consent, verification	TenantPilot only for selection and onboarding draft state; provider execution remains separate	Select connection, Create connection, Continue	none added by this slice

Proportionality Review

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: no
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no
• Current operator problem: the platform-core provider boundary still forces operators and downstream run/audit consumers to rely on Microsoft-specific scope identity even though provider connections are already modeled as managed-environment-bound records.
• Existing structure is insufficient because: the current structure already has shared target-scope and identity helpers, but those helpers still emit Microsoft-shaped fields and context. Leaving them untouched would keep the real platform-core contract Microsoft-specific even if page copy becomes more neutral.
• Narrowest correct implementation: extend the existing target-scope descriptor, identity resolution, provider-connection summary, onboarding readiness, and provider-operation start seams so they emit one neutral shared contract while keeping Microsoft profile detail nested under provider-owned metadata/profile blocks.
• Ownership cost: focused updates across provider resolution, run context, audit metadata, provider-connection resource summaries, onboarding readiness, and their tests. The cost stays bounded because no new table, registry, or framework is introduced.
• Alternative intentionally rejected: a new provider-profile table, a generic provider profile registry, or a broader multi-provider identity framework. Those options add structure without a current-release source-of-truth need and violate the constitution's bounded-extraction bias.
• Release truth: current-release truth; this slice closes an active platform-core/provider-boundary mismatch rather than preparing speculative future providers.

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature, Browser
• Validation lane(s): fast-feedback, confidence, browser
• Why this classification and these lanes are sufficient: feature coverage is the narrowest honest proof for provider-boundary contract changes across target-scope normalization, identity resolution, provider-operation start context, resource semantics, and onboarding readiness. One browser smoke is justified because the operator-facing resource and onboarding flow must show the same summary and action semantics in the real shell.
• New or expanded test families: one provider target-scope or identity feature family, one provider-operation start-gate context family, one provider-connection Filament resource behavior family, one onboarding provider-connection readiness family, and one narrow browser smoke covering the provider-connections plus onboarding path
• Fixture / helper cost impact: moderate. Tests need workspace, managed environment, provider connection, optional provider credential, and focused run fixtures. No new global defaults, provider registries, or browser-wide setup should become implicit.
• Heavy-family visibility / justification: one browser smoke only. No heavy-governance family is justified by this slice.
• Special surface test profile: standard-native-filament, workflow-hub, global-context-shell
• Standard-native relief or required special coverage: ordinary feature coverage is sufficient for the shared contract shifts; one browser smoke is required to prove that provider-connections and onboarding show the same target-scope summary and action affordances on real surfaces.
• Reviewer handoff: reviewers must verify that Filament remains v5 on Livewire v4, provider registration remains in apps/platform/bootstrap/providers.php, ProviderConnectionResource stays non-globally-searchable while continuing to offer View and Edit pages, touched destructive actions still use ->action(...) plus ->requiresConfirmation() and server authorization, no new asset registration appears, and the planned tests prove the shared neutral target-scope contract instead of page-local wording only.
• Budget / baseline / trend impact: moderate feature-local increase only
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• 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)

Scope Boundaries (required for this slice)

In Scope

• document the verified candidate deviation that provider_connections already use managed_environment_id
• normalize the shared provider-connection target-scope contract across connection resolution, identity resolution, audit metadata, resource summaries, onboarding readiness, and provider-operation start context
• normalize the shared provider-identity contract so platform-core seams talk about effective client identity, credential source, and target scope rather than Microsoft tenant context as generic truth
• update provider-operation start context so the shared target_scope payload is provider-neutral and no longer relies on target_scope.entra_tenant_id
• keep Microsoft-specific profile semantics in provider-owned metadata or profile detail, provider-specific links, and support-oriented disclosure
• align ProviderConnectionResource, managed-environment related context, and onboarding readiness on one shared target-scope summary contract
• keep current provider-connection actions, consent links, and capability boundaries intact while clarifying which ones are provider-owned versus platform-core
• keep provider-boundary seam classification explicit in config/provider_boundaries.php and related review proof

Non-Goals

• repeating the already-completed tenant_id -> managed_environment_id move on provider_connections
• introducing a dedicated provider-profile table or any other new persisted profile truth
• introducing a provider capability registry, package engine, provider-neutral artifact taxonomy, or governance-artifact retargeting
• widening the slice into workspace-first RBAC redesign, broader copy or localization neutralization, or cutover quality-gate work reserved for Specs 285-287
• enabling global search for ProviderConnectionResource
• adding a second provider implementation, compatibility shim, backfill path, or speculative multi-provider identity framework

Assumptions

• Spec 279 already completed the managed-environment core cutover and is prerequisite context only.
• Spec 280 already defines the adjacent workspace-first routing shell and remains separate prepared context; 281 must not absorb its route-cutover work.
• ProviderConnection already remains anchored by workspace_id plus managed_environment_id, and the 281 problem is contract extraction rather than relationship migration.
• The existing ProviderConnectionTargetScopeNormalizer, ProviderConnectionTargetScopeDescriptor, ProviderIdentityResolution, ProviderConnectionSurfaceSummary, and provider-connection resource or onboarding surfaces are the correct extension points for this slice.
• Microsoft remains the only implemented provider today, but platform-core seams touched here must still use neutral terms so later provider work is not blocked.
• ProviderConnectionResource remains non-globally-searchable; touched searchable resources such as TenantResource keep their existing valid view destinations.

Risks

• downstream run, audit, or support readers may still expect target_scope.entra_tenant_id even after the start gate writes the neutral shape
• some operator surfaces may migrate to the new target-scope summary while others still read raw entra_tenant_id, leaving the same connection described differently
• dedicated credential validation and blocked reason messaging may stay Microsoft-shaped if CredentialManager and identity-resolution seams are not updated together
• the slice could sprawl into capability-registry, taxonomy, or copy-neutralization work if reviewers allow 283, 284, or 286 concerns to enter the implementation

Candidate Selection Gate Summary

• Selected candidate: 281 - Provider Connection, Provider Scope & Microsoft Profile Extraction
• Source locations:
  • docs/product/spec-candidates.md under the reserved workspace-first or provider-neutral cutover pack
  • docs/product/roadmap.md under the same cutover ordering
• Why selected now: after the completed 279 core cutover and the prepared 280 routing cutover, the next verified blocker is the provider boundary itself. The repo already has target-scope groundwork, but shared provider connection and run identity still leak Microsoft semantics in the platform core.
• Why close alternatives were deferred:
  • 282 depends on 281 because governance-artifact retargeting should inherit provider-neutral connection and run scope instead of another Microsoft-shaped shared contract
  • 283 is capability-registry follow-through and should not be pulled into this slice while the connection or profile contract is still being normalized
  • 284 is a broader artifact-source taxonomy and belongs after the provider-connection and run-scope boundary is neutralized
  • 285 is workspace-first RBAC follow-through and can remain on the current capability model while 281 closes the connection or profile hotspot
  • 286 is broader operator-copy and localization neutralization and should follow the concrete provider-boundary extraction rather than precede it
  • 287 is the cutover quality-gate pack and should harden the finished slices instead of expanding 281
• Smallest viable implementation slice: one neutral shared target-scope and identity contract across existing provider seams plus provider-owned Microsoft profile disclosure on the current resource and onboarding surfaces
• Documented deviations from raw candidate wording:
  • the raw candidate still mentions replacing provider_connections.tenant_id with provider_connections.managed_environment_id, but repo truth already completed that move
  • the raw candidate also proposed a new shared field family around provider_key, external_account_id, provider_metadata, and explicit run-context workspace/environment keys; this package narrows that to existing repo truth by keeping provider, workspace_id, and managed_environment_id where they already exist, using the canonical shared target_scope plus effective_client_identity, and confining provider-specific identifiers or profile detail to nested provider_context and existing provider-owned metadata

Completed-Spec Guardrail Result

• specs/279-workspace-managed-environment-core/spec.md already exists with Status: Ready with approved feature-local exception and remains historical prerequisite context only
• specs/280-workspace-tenancy-environment-routing/spec.md already exists with Status: Ready and remains an adjacent prepared package only; its route-cutover work must not be absorbed into 281
• the target package specs/281-provider-connection-scope/spec.md existed only as the raw template before this update and is the sole spec artifact edited in this package

Deferred Adjacent Candidates

• 282 - Governance Artifact Retargeting to ManagedEnvironment
• 283 - Provider Capability Registry v1
• 284 - Provider-neutral Artifact Source Taxonomy v1
• 285 - Workspace-first RBAC & Environment Access Scoping
• 286 - UI Copy, IA & Localization Neutralization
• 287 - Cutover Quality Gates & No-Legacy Enforcement

User Scenarios & Testing

User Story 1 - Inspect a provider connection with one neutral target-scope summary (Priority: P1)

As an operator, I want provider-connection list and detail surfaces to tell me immediately which managed environment and target scope a connection represents without forcing me to interpret a Microsoft-only field name before I can decide whether the connection is usable.

Why this priority: this is the core operator-facing trust problem in the current seam. If the shared summary remains Microsoft-shaped, later provider-neutral cutover work keeps inheriting that drift.

Independent Test: open the provider-connections list and one connection detail page for a managed environment, then confirm the shared summary shows provider, target scope, and health first while Microsoft profile detail stays nested under a provider-owned disclosure.

Acceptance Scenarios:

1. Given a managed environment has a provider connection, When the operator opens the provider-connections list or detail page, Then the default-visible summary shows provider, target scope, lifecycle, consent, and verification without requiring a Microsoft-only field label to understand the connection identity.
2. Given the operator needs provider-specific consent or troubleshooting data, When they open the provider-owned profile or context disclosure on the connection detail surface, Then Microsoft-specific details appear there without replacing the shared target-scope label set.

---

User Story 2 - Start provider work without Microsoft-shaped shared run context (Priority: P1)

As an operator, I want connection checks and provider operations started from provider-connection or onboarding surfaces to record provider-neutral target-scope context so later run follow-up, audit, and support flows do not depend on Microsoft-only keys.

Why this priority: ProviderOperationStartGate is one of the verified remaining hotspots, and later artifact and taxonomy work depends on this shared execution context becoming neutral first.

Independent Test: start one provider-backed operation from a provider connection and verify that the resulting run can be identified by provider connection and target scope without relying on target_scope.entra_tenant_id as the shared contract.

Acceptance Scenarios:

1. Given an operator starts Check connection, Inventory sync, or Compliance snapshot from a valid provider connection, When the run is created, Then the resulting run context identifies provider connection and target scope through provider-neutral shared fields, with any Microsoft-specific detail nested under provider-owned context only.
2. Given a provider operation is blocked because consent, scope, or credentials are invalid, When the blocked result is shown, Then the operator still sees a usable target-scope summary and blocked reason without the shared contract collapsing back to Microsoft-only field names.

---

User Story 3 - See the same connection story in onboarding and provider settings (Priority: P2)

As an operator, I want the onboarding wizard to describe provider connections with the same target-scope summary used on the provider-connections resource so I do not need to reinterpret the same connection differently just because I am in onboarding.

Why this priority: onboarding is already one of the verified seams reusing provider-connection summaries and audit metadata. Drift here would immediately create a second identity language.

Independent Test: select or create a provider connection from the onboarding wizard and confirm that the displayed target-scope summary matches the one shown on the provider-connections resource for the same record.

Acceptance Scenarios:

1. Given onboarding lists multiple provider connections for the current managed environment, When the operator reviews the choices, Then each option uses the same target-scope summary contract as the provider-connections list and detail surfaces.
2. Given onboarding shows provider verification or supporting links for the selected connection, When the operator inspects that state, Then the readiness surface uses the same shared target-scope and provider-context labels as the provider-connections resource.

---

User Story 4 - Jump from managed-environment detail into provider connections without duplicate truth (Priority: P3)

As an operator, I want the managed-environment detail page to advertise provider-connection state and take me into the provider-connections resource without duplicating the full provider profile summary on the overview page.

Why this priority: this is the boundary between context surfaces and primary decision surfaces. The environment overview should stay calm while still exposing the integration step.

Independent Test: open one managed-environment detail page, use its provider-connections related-context entry, and verify that the overview stays summary-first while the provider-connections resource becomes the primary decision surface.

Acceptance Scenarios:

1. Given a managed environment has an accessible provider connection, When the operator uses the provider-connections related-context entry from the environment view, Then the destination opens the provider-connections resource scoped to that environment and carries the same shared target-scope summary.
2. Given the operator stays on the managed-environment overview page, When they read the provider-connection summary there, Then the page shows only the minimal connection truth needed to decide whether to drill in and does not duplicate full provider-profile detail.

Edge Cases

• A provider connection with missing or invalid target-scope input must stay blocked explicitly and must not fall back to an implicit Microsoft tenant context.
• An unsupported provider or scope combination must fail as an unsupported binding or invalid connection rather than being normalized into a Microsoft-shaped default.
• A dedicated credential payload whose embedded environment or scope hint no longer matches the connection's normalized target scope must fail validation rather than silently reusing stale Microsoft identity.
• Multiple default provider connections for the same managed environment and provider must remain blocked and clearly diagnosable.
• A provider connection record or onboarding selection outside the current workspace or managed environment must resolve as 404 or unavailable, not as a leaked or silently widened option.
• If provider-specific profile data such as domains or portal links are absent, the shared target-scope summary must still render truthfully without forcing a new persisted profile table into scope.

Requirements

Constitution alignment (required): This slice changes provider connection resolution, identity resolution, provider-operation start context, provider-connection admin surfaces, and onboarding readiness. It does not introduce new Microsoft Graph contract registry entries, new provider implementations, or new long-running workflow types.

Constitution alignment (PROP-001 / PROV-001 / BLOAT-001): The slice must stay bounded to current provider-connection and run-context hotspots. No new table, registry, or generic provider framework is justified unless later planning can prove a current-release source-of-truth need.

Constitution alignment (XCUT-001 / UI-FIL-001 / DECIDE-001): The slice must reuse the existing provider-connections resource, existing onboarding wizard, and existing provider-operation start path. It may refine shared summaries and provider-owned detail disclosure, but it must not invent a second provider workbench, a second onboarding picker, or ad-hoc status styling.

Constitution alignment (RBAC-UX): Workspace and managed-environment membership remain the isolation boundaries. Provider manage or run mutations stay server-authorized and confirmation-protected where destructive or high-impact. Navigation-only actions such as Grant admin consent stay capability-gated but do not claim confirmation behavior.

Constitution alignment (TEST-GOV-001 / OPS-UX-START-001): Proof must stay bounded to feature tests plus one browser smoke. Operation start behavior must continue to flow through the shared provider-operation gate or presenter path, with the only change being the shared target-scope and provider-context contract.

Functional Requirements

• FR-001: The system MUST preserve ProviderConnection as the existing workspace-owned, managed-environment-scoped provider binding record and MUST NOT reintroduce tenant_id semantics into provider_connections.
• FR-002: Shared provider-connection target-scope output MUST use provider-neutral fields for provider, scope kind, scope identifier, and scope display name wherever the platform core records or renders connection scope.
• FR-003: ProviderConnectionResolver and related validation paths MUST treat provider plus managed environment plus normalized target scope as the controlling scope contract, not entra_tenant_id as generic platform truth.
• FR-004: Shared provider identity resolution MUST separate neutral identity semantics such as effective client identity, credential source, and target scope from provider-specific profile or context detail.
• FR-005: ProviderIdentityResolution and PlatformProviderIdentityResolver MUST stop using tenantContext as the canonical shared contract term and MUST confine any remaining Microsoft tenant-context semantics to provider-owned profile or context detail.
• FR-006: CredentialManager validation MUST align dedicated credentials with the connection's normalized target scope and provider binding rather than treating a Microsoft-specific field as the only source of truth.
• FR-007: ProviderConnectionTargetScopeNormalizer and ProviderConnectionTargetScopeDescriptor MUST continue to block unsupported provider or scope combinations explicitly and MUST emit the same shared summary contract used by resource, onboarding, audit, and run surfaces.
• FR-008: Provider-connection audit metadata MUST use the neutral target-scope descriptor fields in shared audit context and MUST keep Microsoft-specific identity context nested under provider-owned detail only.
• FR-009: ProviderOperationStartGate MUST write provider-neutral target_scope fields into OperationRun context and MUST NOT use target_scope.entra_tenant_id as the shared contract key.
• FR-010: Any Microsoft-specific scope or profile data still needed by provider-operation follow-up, consent, or support flows MUST live inside a clearly provider-owned nested context or metadata block rather than in the shared target_scope shape.
• FR-011: ProviderConnectionResource list, create, view, and edit surfaces MUST show neutral target-scope labels and summaries in their shared columns, sections, and helper text while moving Microsoft-specific profile detail into provider-owned disclosure.
• FR-012: ProviderConnectionResource MUST remain non-globally-searchable in this slice. Its existing View and Edit pages remain the canonical inspect and mutation surfaces.
• FR-013: TenantResource managed-environment detail summaries and related-context entries that advertise provider connections MUST use the same shared target-scope summary contract as ProviderConnectionResource.
• FR-014: ManagedTenantOnboardingWizard MUST use the same shared target-scope summary contract for provider-connection options, readiness state, and supporting audit metadata as the provider-connections resource.
• FR-015: Provider-specific consent, required-permissions, portal, and troubleshooting detail MUST remain provider-owned guidance and MUST NOT redefine shared platform nouns such as workspace, managed environment, provider connection, or target scope.
• FR-016: The implementation MUST NOT introduce a dedicated provider-profile table, a provider-profile registry, a capability registry, a provider-neutral artifact taxonomy, or any other framework work reserved for Specs 282-287.
• FR-017: The feature MUST preserve the existing provider-connection action family and provider-operation start entry points, changing only the shared connection or profile semantics they expose.
• FR-018: config/provider_boundaries.php and any related review proof touched by implementation MUST classify the remaining Microsoft-specific exceptions explicitly instead of leaving them implicit in platform-core seams.

Authorization and Safety Requirements

• AR-001: Workspace membership MUST remain the first access boundary for provider-connections and onboarding provider-connection flows.
• AR-002: Managed-environment entitlement MUST remain the second access boundary for provider-connections list, detail, create, or edit access and onboarding connection selection.
• AR-003: Non-members or cross-workspace or cross-environment access attempts MUST resolve as 404, while in-scope actors missing provider capabilities MUST resolve as 403.
• AR-004: Mutating provider-connection actions such as setting default, enabling dedicated override, rotating or deleting credentials, reverting to platform, and enabling or disabling the connection MUST remain server-authorized and use confirmation where the existing action contract requires it.
• AR-005: Navigation-only consent actions such as Grant admin consent MUST remain capability-gated and truthful about being navigation, not mutation.
• AR-006: Provider-operation starts triggered from the touched surfaces MUST continue to use the shared provider-operation gate and existing capability checks before any run is created.

Non-Functional Requirements

• NFR-001: Filament remains v5 on Livewire v4.
• NFR-002: Provider registration remains in apps/platform/bootstrap/providers.php; this slice does not move any provider or panel registration into bootstrap/app.php.
• NFR-003: Asset strategy remains unchanged. No new panel or shared asset registration is expected; if a later implementation registers assets unexpectedly, deployment continues to use cd apps/platform && php artisan filament:assets.
• NFR-004: ProviderConnectionResource remains non-globally-searchable, and any touched searchable resource such as TenantResource must keep its valid view destination intact.
• NFR-005: The feature must stay reviewable as one bounded slice and must not silently absorb route-cutover work from Spec 280 or capability, taxonomy, RBAC, copy, or quality-gate work from Specs 282-287.
• NFR-006: The touched Filament surfaces must continue to follow the current TenantPilot enterprise UI standard, existing action hierarchy, and native Filament semantics rather than introducing local card, button, or status styling.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List or Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create or Edit Save+Cancel	Audit log?	Notes / Exemptions
Provider connections list	ProviderConnectionResource -> ListProviderConnections	New connection	recordUrl() clickable row to View	More group containing Edit, Check connection, Inventory sync, Compliance snapshot, Set as default, Enable dedicated override, Rotate dedicated credential, Delete dedicated credential, Revert to platform, Enable connection, Disable connection	none	New connection	N/A	N/A	existing mutation actions already write audit logs where required	Resource remains non-globally-searchable and keeps one inspect model via clickable row
Provider connection view and edit surfaces	ProviderConnectionResource -> ViewProviderConnection, EditProviderConnection, CreateProviderConnection	Grant admin consent plus existing More action group on View; existing Edit or Create header behavior stays native	N/A	none beyond the shared More group on View or Edit	none	N/A	Grant admin consent, More	native save or cancel flow	existing mutation actions already write audit logs where required	Grant admin consent is navigation-only; mutating actions in More remain server-authorized and confirmation-protected where dangerous
Managed-environment onboarding provider-connection step	ManagedTenantOnboardingWizard provider-connection selection or readiness step	none	explicit in-step selector and create or manage actions only	none	none	existing onboarding create or select affordances only	N/A	wizard save or continue semantics only	existing onboarding connection changes already write audit logs	This slice changes summary semantics and supporting links only; it does not introduce a second onboarding action family

Key Entities (include if feature involves data)

• Provider Connection: the existing runtime binding between one managed environment and one provider, including connection type, default state, consent state, verification state, and attached credentials.
• Target Scope Descriptor: the shared neutral summary of what platform scope a provider connection represents, including provider, scope kind, scope identifier, and scope display name.
• Provider Identity Resolution: the shared runtime result that determines effective client identity, credential source, target scope, and blocked or resolved state for one provider connection.
• Provider Profile Detail: provider-owned Microsoft-specific metadata and guidance such as tenant directory identity, consent or required-permissions links, domains, portal links, and similar follow-up detail that must remain secondary to the shared target-scope summary.
• Provider Operation Context: the OperationRun identity and context payload created from a provider-backed start path, linking one run to one provider connection and one normalized target scope.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of affected default-visible provider-connection summaries use neutral target-scope wording instead of requiring a Microsoft-specific field label as the primary identity signal.
• SC-002: An operator can move from managed-environment detail or onboarding to the correct provider-connection detail surface and identify the connection's target scope in 3 interactions or fewer.
• SC-003: 100% of provider operations started from the affected surfaces carry enough shared provider-connection and target-scope information that follow-up run and audit surfaces can identify the target without reconstructing it from Microsoft-only context.
• SC-004: Microsoft-specific consent and profile details remain accessible for troubleshooting and admin-consent follow-up without becoming the primary visible identity vocabulary on affected shared platform surfaces.