TenantAtlas/specs/238-provider-identity-target-scope/spec.md

# Feature Specification: Provider Identity & Target Scope Neutrality

**Feature Branch**: `238-provider-identity-target-scope`  
**Created**: 2026-04-24  
**Status**: Draft  
**Input**: User description: "Promote the next roadmap-fit spec candidate: Provider Identity & Target Scope Neutrality"

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: Shared provider connection semantics still mix neutral platform language with Microsoft-specific tenant identity assumptions, so operators and maintainers cannot tell where platform truth ends and provider detail begins.
- **Today's failure**: Generic-looking provider surfaces and validation paths still imply that a provider connection is fundamentally an Entra tenant binding, which teaches the wrong mental model to operators and quietly deepens provider coupling in shared code.
- **User-visible improvement**: Provider connection create, edit, list, detail, and onboarding-adjacent views describe the connection and its target scope consistently, while Microsoft-specific identity details remain available only when that context is actually needed.
- **Smallest enterprise-capable version**: Neutralize the in-scope provider connection and target-scope contract plus its default UI vocabulary, while preserving current Microsoft onboarding, consent, and verification behavior as bounded provider-specific detail.
- **Architecture center**: The primary deliverable is the shared provider connection target-scope contract. UI vocabulary changes are acceptance evidence for that contract, not the architectural center of the feature.
- **Explicit non-goals**: No second-provider runtime, no provider marketplace, no broad credential model redesign, no replay of the much wider Spec 137 migration scope, no compare-engine changes, and no generic multi-cloud onboarding framework.
- **Permanent complexity imported**: One narrower neutral target-scope contract for shared provider connection truth, one explicit distinction between shared target-scope semantics and provider-owned identity metadata, and focused regression coverage for shared labels, validation, and unsupported-path behavior.
- **Why now**: The roadmap and spec-candidates sequence place this as the next anti-drift hotspot immediately after Spec 237, because leaving provider identity and target scope Microsoft-shaped would undermine the newly hardened boundary before more provider-backed work lands.
- **Why not local**: The problem spans shared persistence semantics, list and detail vocabulary, create and edit flows, onboarding-adjacent copy, and validation behavior. A one-surface copy cleanup would leave the underlying shared contract and other surfaces free to drift again.
- **Approval class**: Core Enterprise
- **Red flags triggered**: Foundation-sounding scope and new boundary vocabulary. Defense: the slice stays bounded to provider connection identity and target-scope semantics, preserves Microsoft-first current product truth, and avoids speculative runtime or marketplace expansion.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitat: 1 | Produktnahe: 1 | Wiederverwendung: 2 | **Gesamt: 10/12**
- **Decision**: approve

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace, tenant
- **Primary Routes**:
  - Existing provider connection collection, create, edit, and detail surfaces under `/admin/provider-connections`
  - Existing tenant-scoped onboarding or connection-setup flows under `/admin/t/{tenant}/...` where provider identity and target scope are shown or chosen
  - Existing consent, verification, and provider-readiness surfaces that display shared connection identity or target-scope summaries
- **Data Ownership**:
  - `provider_connections` remain tenant-owned operational records
  - No new tenant-owned or workspace-owned business entity is introduced
  - Provider-specific identity metadata remains provider-owned detail attached to existing connection truth rather than a new shared platform object
- **RBAC**:
  - Existing workspace membership remains required for all provider connection surfaces
  - Existing tenant entitlement remains required on tenant-context surfaces
  - Existing provider-connection management capabilities continue to authorize create, edit, verification, and consent-adjacent mutations
  - This spec does not introduce a new top-level capability or relax current 404 versus 403 semantics

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: N/A - this slice does not add a new canonical-view surface
- **Explicit entitlement checks preventing cross-tenant leakage**: N/A - in-scope work stays on existing workspace-admin provider-connection surfaces plus existing tenant-scoped onboarding and provider-setup surfaces

## Cross-Cutting / Shared Pattern Reuse *(mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write `N/A - no shared interaction family touched`)*

- **Cross-cutting feature?**: yes
- **Interaction class(es)**: shared provider connection vocabulary, detail summaries, form labels, status messaging, and audit prose
- **Systems touched**: provider connection list, detail, create, edit, onboarding-adjacent setup steps, consent and verification summaries, and any shared filters or helper copy that describe connection target scope
- **Existing pattern(s) to extend**: Spec 237 boundary ownership classification, existing provider connection resource and detail surfaces, and the current shared provider connection resolution path
- **Shared contract / presenter / builder / renderer to reuse**: the existing provider connection management surfaces and the current shared provider connection resolution and summary path remain the single shared path; this spec narrows their vocabulary and target-scope semantics rather than introducing a parallel presenter stack
- **Why the existing shared path is sufficient or insufficient**: the current shared path is sufficient for routing, authorization, and current provider-backed behavior, but it is insufficient because it still treats Microsoft-shaped identity and target-scope semantics as the implied default on generic provider surfaces
- **Allowed deviation and why**: bounded provider-specific descriptors are allowed when the selected provider is Microsoft and the operator genuinely needs tenant- or directory-specific context for consent, troubleshooting, or verification
- **Consistency impact**: provider, provider connection, target scope, consent state, and verification state must use one shared vocabulary across form labels, table columns, detail summaries, validation feedback, and audit prose
- **Review focus**: reviewers must block any generic provider connection surface or shared validation path that reintroduces Microsoft-specific field names, required labels, or defaults without explicit provider-owned justification

## OperationRun UX Impact *(mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an `OperationRun`; otherwise write `N/A - no OperationRun start or link semantics touched`)*

- **Touches OperationRun start/completion/link UX?**: no
- **Shared OperationRun UX contract/layer reused**: N/A
- **Delegated start/completion UX behaviors**: N/A
- **Local surface-owned behavior that remains**: N/A
- **Queued DB-notification policy**: N/A
- **Terminal notification path**: N/A
- **Exception required?**: none

## Provider Boundary / Platform Core Check *(mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write `N/A - no shared provider/platform boundary touched`)*

- **Shared provider/platform boundary touched?**: yes
- **Boundary classification**: mixed
- **Seams affected**: shared provider connection semantics, target-scope descriptors, create and edit field vocabulary, list and detail summaries, validation rules, filter labels, consent and verification summaries, and audit wording
- **Neutral platform terms preserved or introduced**: provider, provider connection, target scope, scope identifier, scope display name, consent state, verification state, readiness summary
- **Provider-specific semantics retained and why**: Microsoft tenant ID, directory ID, admin-consent wording, and Microsoft-specific verification details remain contextual provider-owned detail because current-release truth is still Microsoft-first and operators still need those descriptors on Microsoft paths
- **Why this does not deepen provider coupling accidentally**: the shared platform contract is reduced to neutral connection and target-scope truth, while Microsoft-specific identifiers remain contextual metadata instead of required shared platform fields or default operator vocabulary
- **Follow-up path**: follow-up-spec for broader governed-subject and compare-boundary work; the provider connection identity and target-scope hotspot is resolved in-feature

## UI / Surface Guardrail Impact *(mandatory when operator-facing surfaces are changed; otherwise write `N/A`)*

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Provider connection list and detail | yes | Native Filament resource and infolist primitives | shared provider connection family | table, detail | no | Default language becomes target-scope neutral; Microsoft descriptors stay contextual |
| Provider connection create and edit | yes | Native Filament forms and sections | shared provider connection family | form, section | no | Existing create and edit flow remains; only shared contract and vocabulary are narrowed |
| Tenant onboarding provider step | yes | Native wizard and action surfaces | shared onboarding and provider family | wizard step | no | Existing onboarding path remains; scope and identity language become neutral by default |

## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)*

| 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 connection list and detail | Primary Decision Surface | Decide whether the connection points at the right target scope and what follow-up action is needed | Provider, target scope, consent state, verification state, and readiness summary | Raw provider-specific identifiers, consent diagnostics, low-level verification detail | Primary because this is the operational management surface where operators decide whether the connection is correctly scoped and usable | Follows provider setup and troubleshooting workflow rather than storage internals | Removes the need to infer meaning from raw tenant identifiers or mixed status labels |
| Provider connection create and edit | Primary Decision Surface | Choose the connection target and save it with the correct scope semantics | Provider choice, target-scope summary, required neutral fields, and provider-specific fields only when relevant | Secondary provider-specific guidance and troubleshooting detail | Primary because the operator is defining connection truth here, not just inspecting it later | Follows setup and correction workflow directly | Prevents incorrect scope choices caused by Microsoft-first default wording |
| Tenant onboarding provider step | Primary Decision Surface | Confirm that onboarding is connecting the intended target scope before continuing | Provider, target-scope summary, and the next action needed to continue onboarding | Provider-specific context such as Microsoft tenant identity when selected | Primary because onboarding must answer what is being connected before the operator commits to the next step | Keeps onboarding focused on the current tenant workflow | Reduces ambiguity between platform-neutral setup and Microsoft-specific details |

## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)*

| 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 connection list and detail | List / Table / Bulk | CRUD / List-first Resource | Inspect or edit the connection target scope | Full-row click to detail | allowed | One inline safe shortcut plus More | More or detail header only | /admin/provider-connections | existing provider connection detail route | Workspace, provider, target scope | Provider connections / Provider connection | What scope the connection represents and whether it is consented and verified | none |
| Provider connection create and edit | Record / Detail / Edit | Create/Edit Form | Save the connection with the correct target scope | Explicit create or edit page only | forbidden | Secondary guidance lives in section help text, not competing actions | Existing dangerous lifecycle actions remain off the create page and grouped on detail or edit where already supported | /admin/provider-connections | existing provider connection detail route after save | Provider and target scope | Provider connection | Which target scope will be connected and which fields are provider-neutral versus provider-specific | none |
| Tenant onboarding provider step | Workflow / Wizard / Launch | Wizard / Step-driven Flow | Continue onboarding with the confirmed provider target scope | Existing onboarding step | forbidden | Secondary navigation remains contextual only | Destructive actions are out of scope | existing tenant onboarding route | existing onboarding step route | Workspace, tenant, provider, target scope | Onboarding / Provider setup step | Which scope is being connected before the operator continues | none |

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| 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 connection list and detail | Workspace owner, tenant manager, support operator | Decide whether a provider connection is correctly scoped and ready for use | List and detail | What does this connection point to, and is it ready? | Provider, target scope, consent state, verification state, readiness summary | Raw tenant or directory identifiers, provider-specific verification detail | consent, verification, readiness | TenantPilot only for inspection; Microsoft tenant only when operator triggers existing consent or verification actions | View connection, Edit connection, Retry consent, Run verification | Existing destructive lifecycle actions only where already supported |
| Provider connection create and edit | Workspace owner or tenant manager | Create or correct a provider connection without encoding the wrong target-scope meaning | Create/Edit form | Am I connecting the correct scope, and are these the right fields for this provider? | Provider selection, target-scope summary, neutral required fields, contextual provider-specific fields | Provider-specific troubleshooting guidance | readiness prerequisites only | TenantPilot only until existing provider-facing consent or verification steps are invoked | Save connection, Cancel | none added |
| Tenant onboarding provider step | Tenant manager or onboarding operator | Continue onboarding with the intended provider target scope | Wizard step | What target scope am I connecting right now? | Provider, target-scope summary, current onboarding next step | Provider-specific detail needed for consent or troubleshooting | onboarding progress, consent readiness, verification readiness | TenantPilot onboarding flow and existing provider-facing consent actions | Continue onboarding, Open connection setup where already present | none added |

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no
- **New persisted entity/table/artifact?**: no
- **New abstraction?**: yes
- **New enum/state/reason family?**: no
- **New cross-domain UI framework/taxonomy?**: no
- **Current operator problem**: Operators and maintainers must currently infer shared provider connection meaning from Microsoft-specific labels and identifiers, which creates wrong setup decisions and teaches the wrong platform truth.
- **Existing structure is insufficient because**: Spec 237 classifies seam ownership but does not yet narrow the concrete connection and target-scope contract where Microsoft-shaped semantics are still visible by default.
- **Narrowest correct implementation**: Reuse the existing provider connection surfaces and resolution path, replace only the shared identity and target-scope descriptor/contract semantics, and keep provider-specific detail contextual instead of building a new provider framework.
- **Ownership cost**: The codebase must keep one neutral vocabulary for shared provider connection truth, maintain focused tests that guard default labels and validation behavior, and review provider-specific additions more carefully on shared surfaces.
- **Alternative intentionally rejected**: Reusing the broader old Spec 137 scope was rejected because it mixes identity migration, dedicated credential design, and larger onboarding changes. Pure copy cleanup was rejected because it would leave the shared contract Microsoft-shaped underneath.
- **Release truth**: current-release truth with bounded anti-drift hardening

### 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 *(mandatory for runtime behavior changes)*

- **Test purpose / classification**: Unit, Feature
- **Validation lane(s)**: fast-feedback, confidence
- **Why this classification and these lanes are sufficient**: the change is proven by shared contract behavior plus operator-visible list, detail, create, edit, and onboarding semantics. Narrow unit coverage proves neutral target-scope mapping and validation, while focused feature coverage proves the operator-visible surfaces and authorization behavior.
- **New or expanded test families**: focused provider connection neutrality guard tests only
- **Fixture / helper cost impact**: low to moderate; tests need existing workspace, tenant, membership, provider connection, and provider-specific metadata fixtures, but no new heavy provider harness or browser stack
- **Heavy-family visibility / justification**: none
- **Special surface test profile**: standard-native-filament
- **Standard-native relief or required special coverage**: ordinary feature coverage is sufficient; no browser or heavy-governance lane is justified for this slice
- **Reviewer handoff**: reviewers must confirm that tests prove default neutral target-scope semantics, contextual Microsoft detail retention, unchanged 404 versus 403 behavior, and explicit unsupported-path handling rather than only asserting copy fragments
- **Budget / baseline / trend impact**: none expected beyond a small increase in provider connection feature assertions
- **Escalation needed**: none
- **Active feature PR close-out entry**: Guardrail
- **Planned validation commands**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php tests/Unit/Badges/ProviderConnectionBadgesTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php tests/Feature/ManagedTenantOnboardingWizardTest.php`
  - `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Choose the Right Target Scope (Priority: P1)

As a workspace or tenant admin, I want the provider connection setup flow to describe the target scope in neutral platform language so I can tell what I am connecting before I save it.

**Why this priority**: This is the main operator-facing trust problem. If setup still implies that every connection is fundamentally an Entra tenant binding, the shared platform contract remains misleading.

**Independent Test**: Can be fully tested by opening the create or edit flow, choosing an in-scope provider, and confirming that shared fields and summaries use target-scope language while provider-specific fields appear only when the selected provider needs them.

**Acceptance Scenarios**:

1. **Given** an operator opens the provider connection create flow, **When** they review the default shared fields, **Then** the form describes provider and target scope in neutral platform language rather than Microsoft-specific defaults.
2. **Given** the selected provider is Microsoft, **When** the operator reaches provider-specific consent or verification context, **Then** the UI may show tenant or directory-specific detail without redefining the shared target-scope meaning.

---

### User Story 2 - Inspect Connection Meaning Without Guesswork (Priority: P1)

As an operator inspecting existing provider connections, I want list and detail surfaces to show provider, target scope, consent state, and verification state separately so I can understand what the connection represents and what follow-up is needed.

**Why this priority**: The day-to-day management surface must become trustworthy. If operators still need to infer meaning from raw IDs or mixed status fields, the spec has not delivered its main value.

**Independent Test**: Can be fully tested by loading the list and detail surfaces for representative provider connections and confirming that the shared summary stays neutral while provider-specific identifiers remain secondary detail.

**Acceptance Scenarios**:

1. **Given** a provider connection is listed on the shared resource page, **When** the operator scans the row, **Then** they can see the provider, target scope, consent state, and verification state without reading raw provider-specific IDs.
2. **Given** the operator opens connection detail, **When** provider-specific Microsoft information exists, **Then** it appears as contextual detail rather than the primary shared identity of the connection.

---

### User Story 3 - Extend Shared Provider Surfaces Safely (Priority: P2)

As a maintainer or reviewer, I want shared provider connection semantics to stay neutral by default so future provider-related changes do not silently reintroduce Microsoft-first platform truth.

**Why this priority**: The slice is justified not only by current UI clarity but by preventing the same hotspot from reopening as more provider-backed work lands.

**Independent Test**: Can be fully tested by exercising the focused regression coverage and confirming that a generic provider surface cannot require Microsoft-specific shared fields or default labels without explicit provider-owned justification.

**Acceptance Scenarios**:

1. **Given** a generic provider connection surface or shared validation path is extended, **When** Microsoft-specific identity labels are introduced as the default shared contract, **Then** focused regression coverage fails visibly.
2. **Given** a Microsoft-specific surface still needs tenant or directory detail, **When** the same coverage runs, **Then** the contextual provider-owned detail remains allowed without forcing those labels into the generic contract.

### Edge Cases

- A provider connection may already have valid target-scope summary data but be missing provider-specific Microsoft identity detail, and the shared surface must stay interpretable without pretending the connection is fully ready.
- A Microsoft connection may legitimately need tenant or directory identifiers for consent or troubleshooting, but those identifiers must not become the default label set on generic provider surfaces.
- Existing rows may still contain legacy Microsoft-shaped fields; in-scope surfaces must present neutral target-scope truth without silently promoting legacy fields back into shared platform defaults.
- Unauthorized users must not learn target-scope or provider identity details through list filters, detail summaries, or onboarding-adjacent helper copy.
- Changing the selected provider in a create or edit flow must update required fields and helper copy without leaving stale Microsoft-specific wording behind.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature does not introduce new Microsoft Graph endpoints, new long-running operations, or new persisted business entities. It narrows the shared contract and UI semantics for existing provider connection create, edit, view, consent, and verification flows. Any in-scope create or update mutation remains server-authorized and auditable.

**Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001):** The feature adds one narrower shared abstraction for target-scope semantics because the existing shared connection contract still encodes provider-specific truth by default. It does not add new persistence, new state families, or new cross-domain UI taxonomy.

**Constitution alignment (XCUT-001):** This feature is cross-cutting across provider connection forms, lists, details, onboarding-adjacent setup, validation feedback, and audit prose. It extends the existing shared provider connection path rather than introducing a second presenter or page-local vocabulary layer.

**Constitution alignment (PROV-001):** Shared provider connection and target-scope truth remain platform-core. Provider-specific identity descriptors, consent wording, and Microsoft verification detail remain provider-owned. The spec keeps provider-specific semantics out of the default shared contract and records broader governed-subject and compare semantics as later follow-up work.

**Constitution alignment (TEST-GOV-001):** Proof stays in narrow unit and feature lanes. No browser or heavy-governance family is added. Any helper introduced for provider connection neutrality coverage must keep workspace, tenant, membership, and provider context explicit rather than default.

**Constitution alignment (OPS-UX):** N/A - this slice does not create, start, or redesign an `OperationRun`.

**Constitution alignment (OPS-UX-START-001):** N/A - no `OperationRun` start or link semantics are changed.

**Constitution alignment (RBAC-UX):** In-scope surfaces remain on the tenant and workspace admin plane. Non-members or actors lacking tenant entitlement remain 404. Members lacking the relevant capability remain 403. Authorization stays server-side for create, edit, consent-adjacent, and verification mutations. Existing security-sensitive actions remain confirmation-gated and audited.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable.

**Constitution alignment (BADGE-001):** Consent and verification labels remain centralized; this spec does not introduce a new badge family or a second mapping layer.

**Constitution alignment (UI-FIL-001):** UI-FIL-001 is satisfied. In-scope operator-facing changes stay on native Filament forms, tables, infolists, sections, and existing shared UI primitives. No local replacement markup or page-local status language is introduced.

**Constitution alignment (UI-NAMING-001):** The target object is the provider connection and its target scope. Operator verbs remain existing verbs such as connect, edit, retry consent, and run verification. The same provider and target-scope vocabulary must be preserved across buttons, headings, helper copy, validation feedback, and audit prose.

**Constitution alignment (DECIDE-001):** The affected provider connection and onboarding surfaces are primary decision surfaces because they answer what is being connected and whether the connection is correctly scoped. Provider-specific diagnostics remain secondary detail.

**Constitution alignment (UI-CONST-001 / UI-SURF-001 / ACTSURF-001 / UI-HARD-001 / UI-EX-001 / UI-REVIEW-001 / HDR-001):** The chosen action-surface classes, inspect models, grouped action placement, scope signals, canonical nouns, and default-visible truth are captured in the surface tables above. No exception is required.

**Constitution alignment (ACTSURF-001 - action hierarchy):** This spec does not add new action families. Existing navigation and mutation placement remain unchanged, and no mixed catch-all action structure is introduced.

**Constitution alignment (OPSURF-001):** The default-visible content stays operator-first by surfacing provider, target scope, consent state, and verification state before raw provider-specific identifiers. Diagnostics stay secondary and contextual.

**Constitution alignment (UI-SEM-001 / LAYER-001 / TEST-TRUTH-001):** The feature introduces only the minimum shared semantic tightening required to keep provider-specific identity detail from masquerading as platform-core truth. Tests focus on operator-visible meaning and boundary consequences rather than thin presentation indirection alone.

**Constitution alignment (Filament Action Surfaces):** The Action Surface Contract is satisfied. Each affected surface keeps one primary inspect or open model, redundant View actions remain absent, empty action groups remain absent, and destructive actions stay in their existing safe placements. The UI Action Matrix below records the in-scope surfaces.

**Constitution alignment (UX-001 — Layout & Information Architecture):** In-scope create and edit forms continue to use the existing sectioned Filament layout, view pages continue to use the existing detail or infolist presentation, empty states keep one primary CTA, and tables continue to expose core searchable and filterable dimensions such as provider and target scope. No UX-001 exemption is required.

### Functional Requirements

- **FR-238-001**: The shared provider connection contract MUST distinguish neutral provider-connection truth from provider-specific identity metadata.
- **FR-238-002**: In-scope shared create, edit, list, and detail surfaces MUST use neutral default vocabulary for provider connection and target scope.
- **FR-238-003**: The shared provider connection target-scope descriptor/contract MUST remain understandable through neutral fields such as scope kind, scope identifier, and scope display name without assuming Microsoft directory semantics as the default meaning.
- **FR-238-004**: Microsoft-specific tenant, directory, consent, and verification descriptors MAY appear only as contextual provider-owned detail when the selected provider is Microsoft.
- **FR-238-005**: Shared validation and persistence paths MUST NOT require Microsoft-specific fields unless the selected provider explicitly needs them through provider-owned rules.
- **FR-238-006**: Provider connection list and detail surfaces MUST show provider, target scope, consent state, and verification state as separate default-visible dimensions.
- **FR-238-007**: Shared filters, columns, section headings, and detail summaries for provider connections MUST NOT use Microsoft-specific nouns as the default labels.
- **FR-238-008**: Existing Microsoft onboarding, consent, and verification flows MUST preserve the provider-specific detail operators need without redefining the shared target-scope contract.
- **FR-238-009**: Unsupported provider or target-scope combinations encountered on shared paths MUST fail explicitly rather than inheriting Microsoft defaults.
- **FR-238-010**: Existing authorization behavior for provider connection surfaces MUST remain unchanged, including 404 versus 403 semantics.
- **FR-238-011**: Existing security-sensitive provider connection mutations MUST remain confirmation-gated and auditable.
- **FR-238-012**: The first implementation slice MUST cover provider connection list, detail, create, edit, and tenant onboarding-adjacent setup surfaces.
- **FR-238-013**: The feature MUST NOT introduce a second-provider runtime, provider marketplace, or broad credential model redesign.
- **FR-238-014**: Audit events for in-scope provider connection create or update flows MUST describe target scope in neutral vocabulary while still recording provider context.
- **FR-238-015**: Regression coverage MUST fail if a generic provider connection surface reintroduces Microsoft-specific default labels or required shared fields without explicit provider-owned justification.
- **FR-238-016**: Shared provider/platform seams MUST NOT introduce new Microsoft-specific default labels, filter labels, required fields, validation messages, audit prose, or helper copy unless the path is explicitly provider-owned and scoped to the Microsoft provider.
- **FR-238-017**: Any new target-scope helper, descriptor, or normalization path MUST preserve the distinction between neutral platform scope truth and provider-owned identity metadata.

### Non-Goals

- Reopening the broader connection-type and credential migration work from Spec 137
- Adding a second provider or a provider marketplace workflow
- Redesigning provider verification or consent execution logic end to end
- Renaming every provider-related term in the product outside the in-scope shared connection and target-scope hotspot
- Introducing a new governed-subject taxonomy or compare orchestration layer

### Assumptions

- Current-release product truth remains Microsoft-first, but shared provider connection semantics must no longer imply that Microsoft identity is the default platform contract.
- Existing provider connection resources, onboarding steps, consent flows, and verification flows remain in place and are narrowed rather than rebuilt.
- Existing operator roles and capabilities already cover the in-scope provider connection surfaces.
- Legacy Microsoft-shaped fields may still exist on some rows, but this spec prefers canonical replacement on in-scope shared surfaces instead of compatibility shims.

### Dependencies

- Boundary ownership classification from `specs/237-provider-boundary-hardening/spec.md`
- Existing provider connection resource and detail surfaces
- Existing onboarding, consent, and verification flows that display provider connection identity or scope
- Existing audit logging and authorization infrastructure for provider connections

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Provider connection list | existing provider connection Filament resource | `New connection` | `recordUrl()` to detail | `Edit`, `More` | Existing grouped bulk actions only where already supported | `Connect provider` | `Edit`, `Retry consent`, `Run verification`, `More` | `Save` and `Cancel` on create and edit pages | yes | Default labels become provider and target-scope neutral; no exemption |
| Provider connection detail | existing provider connection detail surface | `Edit`, `Retry consent`, `Run verification` | detail page is the only primary inspect model | none added | none | n/a | `Edit`, `Retry consent`, `Run verification`, `More` | `Save` and `Cancel` on edit page | yes | Provider-specific Microsoft identifiers remain contextual secondary detail |
| Tenant onboarding provider step | existing tenant onboarding provider setup step | none added | existing wizard step only | none | none | existing provider setup CTA remains single primary CTA | contextual open-setup action only where already supported | existing continue and cancel flow remains | yes | Step remains native; only shared target-scope semantics are narrowed |

### Key Entities *(include if feature involves data)*

- **Provider Connection**: The tenant-owned record that represents a provider-backed connection and its readiness for use.
- **Target Scope**: The neutral platform description of what the connection points to, expressed through shared fields such as scope kind, scope identifier, and scope display name.
- **Provider-Specific Identity Metadata**: Contextual provider-owned detail such as Microsoft tenant or directory identifiers that operators may need for consent, verification, or troubleshooting.
- **Connection Readiness Summary**: The operator-facing combination of consent state and verification state used to explain whether the connection is usable.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-238-001**: In covered provider connection list, detail, create, edit, and onboarding surfaces, 100% of default shared labels use neutral provider and target-scope language rather than Microsoft-specific defaults.
- **SC-238-002**: In covered Microsoft scenarios, 100% of required tenant or directory detail remains available contextually without becoming the default shared identity language of the connection.
- **SC-238-003**: In focused operator-visible coverage, users can distinguish provider, target scope, consent state, and verification state without relying on raw provider-specific identifiers to infer meaning.
- **SC-238-004**: In all covered unsupported or missing-context scenarios, shared validation paths fail explicitly rather than inheriting Microsoft-first fallback behavior.
- **SC-238-005**: In all covered create, update, and security-sensitive mutation scenarios, the audit trail records workspace, tenant, provider, and target-scope context.
- **SC-238-006**: Focused guard or regression coverage fails when shared provider/platform seams introduce Microsoft-specific default labels, filters, validation messages, audit prose, or helper copy outside explicitly provider-owned Microsoft paths.