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

description
Task list for Provider Identity & Target Scope Neutrality

Tasks: Provider Identity & Target Scope Neutrality

Input: Design documents from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/238-provider-identity-target-scope/
Prerequisites: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/238-provider-identity-target-scope/plan.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/238-provider-identity-target-scope/spec.md (required), /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/238-provider-identity-target-scope/research.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/238-provider-identity-target-scope/data-model.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/238-provider-identity-target-scope/contracts/, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/238-provider-identity-target-scope/quickstart.md

Tests: REQUIRED (Pest) for runtime behavior changes; keep proof in the narrow Unit and Feature lanes named in the plan
Operations: No new OperationRun type or Monitoring surface is introduced; preserve current health-check and verification run behavior while neutralizing shared target-scope semantics
RBAC: Preserve existing workspace and tenant authorization semantics on touched provider connection and onboarding surfaces, including 404 for non-members and 403 for members missing capability
Provider Boundary: Shared target-scope truth remains platform-core; Microsoft tenant, directory, consent, and authority details remain explicitly bounded provider-owned contextual metadata

Organization: Tasks are grouped by user story so the shared target-scope contract, shared-surface adoption, and guardrail close-out can be implemented and validated incrementally.

Test Governance Checklist

• Lane assignment stays Unit plus Feature and remains the narrowest sufficient proof for the changed behavior.
• New or changed tests stay in existing provider connection, Filament, audit, onboarding, and guard families; no browser or heavy-governance lane is added.
• Shared helpers, factories, fixtures, and provider context defaults stay cheap by default; do not introduce a default provider-world bootstrap.
• Planned validation commands cover descriptor normalization, explicit unsupported-path handling, shared-surface neutrality, unchanged auth and confirmation behavior, onboarding reuse, audit wording, and guardrails without widening scope.
• Surface test profile remains standard-native-filament with one onboarding wizard-step extension.
• Any remaining provider-specific hotspot resolves as document-in-feature or follow-up-spec, not as silent platform-core truth.

Phase 1: Setup (Shared Context)

Purpose: Confirm the current hotspots, owning files, and existing proof lanes before introducing the shared target-scope contract.

• T001 Review the current Microsoft-shaped shared-surface hotspots in apps/platform/app/Filament/Resources/ProviderConnectionResource.php, apps/platform/app/Services/Providers/ProviderIdentityResolution.php, and apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
• T002 [P] Review existing provider connection audit and UI enforcement coverage in apps/platform/tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php and apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php
• T003 [P] Review existing provider-owned exception seams in apps/platform/app/Services/Providers/ProviderIdentityResolver.php, apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php, and apps/platform/app/Services/Providers/ProviderConnectionMutationService.php

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Add the shared target-scope primitives that every user story depends on.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T004 Create the shared descriptor primitives in apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeDescriptor.php and apps/platform/app/Support/Providers/TargetScope/ProviderIdentityContextMetadata.php
• T005 [P] Create the shared normalization and surface-summary helpers in apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php and apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php
• T006 Update apps/platform/app/Services/Providers/ProviderConnectionResolution.php and apps/platform/app/Services/Providers/ProviderIdentityResolution.php to expose neutral target-scope data plus provider-owned contextual metadata
• T007 [P] Align resolver consumption of the new neutral descriptor in apps/platform/app/Services/Providers/ProviderConnectionResolver.php, apps/platform/app/Services/Providers/ProviderIdentityResolver.php, and apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php
• T008 [P] Sync the shared descriptor, normalization, surface-summary, and neutrality-evaluation shapes with specs/238-provider-identity-target-scope/contracts/provider-identity-target-scope.logical.openapi.yaml

Checkpoint: Shared target-scope primitives exist; user story work can now build on one explicit neutral contract.

---

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

Goal: Make the create and edit flow describe provider connection scope in neutral platform language before the operator saves it.

Independent Test: Open the provider connection create or edit flow, choose an in-scope provider, and verify the shared fields and helper copy use neutral target-scope language while Microsoft-specific identity only appears contextually when the selected provider is Microsoft.

Tests for User Story 1

• T009 [P] [US1] Add descriptor normalization coverage, including explicit unsupported provider or target-scope combinations and missing-context failures, in apps/platform/tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php
• T010 [P] [US1] Add create and edit neutral target-scope flow coverage, including explicit unsupported combination and missing-context failures, in apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php
• T011 [P] [US1] Extend shared authorization and UI enforcement coverage for provider connection create, list, and detail target-scope surfaces, including unchanged 404 versus 403 behavior, in apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php

Implementation for User Story 1

• T012 [US1] Replace shared create and edit form fields plus helper text with neutral target-scope wording in apps/platform/app/Filament/Resources/ProviderConnectionResource.php
• T013 [US1] Route create and edit normalization plus mutation messaging through the shared target-scope helper in apps/platform/app/Services/Providers/ProviderConnectionMutationService.php and apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php
• T014 [US1] Keep Microsoft-specific contextual identity available only on Microsoft create and edit paths in apps/platform/app/Services/Providers/ProviderIdentityResolver.php and apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php
• T015 [US1] Run the US1 proof lane documented in specs/238-provider-identity-target-scope/quickstart.md against apps/platform/tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php, apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php, and apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php

Checkpoint: User Story 1 is independently deliverable as the core setup-flow neutrality slice.

---

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

Goal: Make list and detail surfaces show provider, target scope, consent state, and verification state separately without forcing operators to infer meaning from raw Microsoft identifiers.

Independent Test: Load provider connection list and detail surfaces for representative connections and verify the default-visible summary stays neutral while provider-specific identity remains secondary diagnostic detail.

Tests for User Story 2

• T016 [P] [US2] Add list and detail neutrality coverage plus default-visible status separation in apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php and apps/platform/tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php
• T017 [P] [US2] Add shared identity-resolution neutrality coverage in apps/platform/tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php
• T018 [P] [US2] Extend badge and summary assertions that keep consent and verification distinct in apps/platform/tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php and apps/platform/tests/Unit/Badges/ProviderConnectionBadgesTest.php

Implementation for User Story 2

• T019 [US2] Replace default list, table, infolist, and detail target-scope labels plus summaries in apps/platform/app/Filament/Resources/ProviderConnectionResource.php
• T020 [P] [US2] Align derived connection summaries with the shared target-scope descriptor in apps/platform/app/Services/Providers/ProviderConnectionStateProjector.php and apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php
• T021 [US2] Keep contextual Microsoft identity and diagnostics secondary to neutral target-scope truth in apps/platform/app/Services/Providers/ProviderConnectionResolution.php and apps/platform/app/Filament/Resources/ProviderConnectionResource.php
• T022 [US2] Run the US2 proof lane documented in specs/238-provider-identity-target-scope/quickstart.md against apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php, apps/platform/tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php, apps/platform/tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php, apps/platform/tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php, and apps/platform/tests/Unit/Badges/ProviderConnectionBadgesTest.php

Checkpoint: User Stories 1 and 2 both work independently, with shared setup and inspection surfaces aligned to one neutral target-scope contract.

---

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

Goal: Reuse the same neutral target-scope contract in onboarding, mutation copy, and audit wording, and block future regressions on shared provider surfaces.

Independent Test: Exercise onboarding, audit, UI enforcement, and guard coverage to verify shared provider surfaces cannot reintroduce Microsoft-specific default labels, filters, required fields, validation messages, helper copy, or audit prose without explicit provider-owned justification.

Tests for User Story 3

• T023 [P] [US3] Add onboarding provider-setup neutrality coverage plus unchanged 404 versus 403 leakage protection in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php
• T024 [P] [US3] Extend shared audit wording coverage and sensitive-action confirmation-gate coverage in apps/platform/tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php and apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php
• T025 [P] [US3] Add shared-surface guard coverage for Microsoft-specific default labels, filters, required fields, validation messages, helper copy, and audit prose in apps/platform/tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php

Implementation for User Story 3

• T026 [US3] Reuse the shared target-scope descriptor in the onboarding provider setup step in apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
• T027 [US3] Align provider connection action labels, filter labels, section headings, helper copy, validation messages, mutation messaging, and audit wording with neutral provider and target-scope vocabulary in apps/platform/app/Filament/Resources/ProviderConnectionResource.php and apps/platform/app/Services/Providers/ProviderConnectionMutationService.php
• T028 [US3] Codify the provider-owned contextual exception boundary from specs/237-provider-boundary-hardening/spec.md and the review-stop expectations in specs/238-provider-identity-target-scope/contracts/provider-identity-target-scope.logical.openapi.yaml and specs/238-provider-identity-target-scope/quickstart.md
• T029 [US3] Run the US3 proof lane documented in specs/238-provider-identity-target-scope/quickstart.md against apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php, apps/platform/tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php, apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php, and apps/platform/tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php

Checkpoint: All user stories are independently functional, and shared provider surfaces are guarded against reintroducing Microsoft-first default truth.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Finalize formatting, validation, and guardrail close-out across the full slice.

• T030 [P] Refresh the implementation notes, logical contract wording, and validation commands in specs/238-provider-identity-target-scope/plan.md, specs/238-provider-identity-target-scope/quickstart.md, and specs/238-provider-identity-target-scope/contracts/provider-identity-target-scope.logical.openapi.yaml
• T031 [P] Run formatting for touched PHP files in apps/platform/app/Filament/Resources/ProviderConnectionResource.php, apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php, apps/platform/app/Services/Providers/, apps/platform/app/Support/Providers/TargetScope/, apps/platform/tests/Unit/Providers/, and apps/platform/tests/Feature/
• T032 Run the final focused validation lane from specs/238-provider-identity-target-scope/quickstart.md against apps/platform/tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php, apps/platform/tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php, apps/platform/tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php, apps/platform/tests/Unit/Badges/ProviderConnectionBadgesTest.php, apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php, apps/platform/tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php, apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php, apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php, apps/platform/tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php, and apps/platform/tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php
• T033 Record the guardrail close-out, document-in-feature disposition, and deferred provider-boundary follow-up status in specs/238-provider-identity-target-scope/plan.md and specs/238-provider-identity-target-scope/quickstart.md

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies; can start immediately.
• Foundational (Phase 2): Depends on Setup completion and blocks all user stories.
• User Story 1 (Phase 3): Depends on Foundational completion.
• User Story 2 (Phase 4): Depends on Foundational completion and should follow the stable descriptor contract from User Story 1 on shared resource surfaces.
• User Story 3 (Phase 5): Depends on Foundational completion and should follow User Story 1 because onboarding and audit wording reuse the same target-scope descriptor and mutation vocabulary.
• Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

• User Story 1 (P1): This is the MVP and should ship first.
• User Story 2 (P1): Conceptually independent after Phase 2, but it reuses the target-scope descriptor and shared resource semantics stabilized in User Story 1.
• User Story 3 (P2): Conceptually independent after Phase 2, but its onboarding, audit, confirmation-gate, exception-boundary, and guardrail tasks remain part of the shippable slice because they satisfy FR-238-011, FR-238-014, FR-238-015, and FR-238-016.

Within Each User Story

• Tests should be written and fail before the corresponding implementation tasks.
• Shared descriptor and resolution changes must land before any surface-specific adoption task consumes them.
• Serialize edits in apps/platform/app/Filament/Resources/ProviderConnectionResource.php when multiple story tasks touch the same resource file.
• Finish each story's verification task before moving to the next priority when working sequentially.

Parallel Opportunities

• Setup: T002 and T003 can run in parallel.
• Foundational: T005, T007, and T008 can run in parallel after T004 defines the descriptor primitives.
• US1 tests: T009, T010, and T011 can run in parallel.
• US1 implementation: T013 and T014 can run in parallel after T012 settles the shared form contract.
• US2 tests: T016, T017, and T018 can run in parallel.
• US2 implementation: T020 can run in parallel with T021, but both should follow T019 because ProviderConnectionResource.php is shared.
• US3 tests: T023, T024, and T025 can run in parallel.
• US3 implementation: T026 and T028 can run in parallel; T027 should serialize after T019 and T012 because it touches ProviderConnectionResource.php.
• Polish: T030 and T031 can run in parallel before T032 and T033.

---

Parallel Example: User Story 1

# Run US1 coverage in parallel:
T009 apps/platform/tests/Unit/Providers/ProviderConnectionTargetScopeDescriptorTest.php
T010 apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php
T011 apps/platform/tests/Feature/Filament/ProviderConnectionsUiEnforcementTest.php

# Then split the non-overlapping implementation follow-up:
T013 apps/platform/app/Services/Providers/ProviderConnectionMutationService.php and apps/platform/app/Support/Providers/TargetScope/ProviderConnectionTargetScopeNormalizer.php
T014 apps/platform/app/Services/Providers/ProviderIdentityResolver.php and apps/platform/app/Services/Providers/PlatformProviderIdentityResolver.php

---

Parallel Example: User Story 2

# Run US2 summary and identity coverage in parallel:
T016 apps/platform/tests/Feature/ProviderConnections/ProviderConnectionNeutralitySpec238Test.php and apps/platform/tests/Feature/ProviderConnections/ProviderConnectionViewsDbOnlyRenderingSpec081Test.php
T017 apps/platform/tests/Unit/Providers/ProviderIdentityResolutionNeutralityTest.php
T018 apps/platform/tests/Unit/Providers/ProviderConnectionBadgeMappingTest.php and apps/platform/tests/Unit/Badges/ProviderConnectionBadgesTest.php

# Then split non-overlapping implementation follow-up:
T020 apps/platform/app/Services/Providers/ProviderConnectionStateProjector.php and apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php
T021 apps/platform/app/Services/Providers/ProviderConnectionResolution.php

---

Parallel Example: User Story 3

# Run US3 onboarding, audit, and guard coverage in parallel:
T023 apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php
T024 apps/platform/tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php
T025 apps/platform/tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php

# Then split non-overlapping implementation follow-up:
T026 apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
T028 specs/238-provider-identity-target-scope/contracts/provider-identity-target-scope.logical.openapi.yaml and specs/238-provider-identity-target-scope/quickstart.md

---

Implementation Strategy

MVP / Shippable Slice

1. Complete Phase 1: Setup.
2. Complete Phase 2: Foundational.
3. Complete Phase 3: User Story 1 and Phase 4: User Story 2.
4. Complete all of Phase 5: User Story 3 so onboarding, audit wording, confirmation-gate proof, exception-boundary codification, and guard coverage land with the same shippable slice.
5. Stop and validate with T015, T022, T029, and T032.
6. Review whether list, detail, create, edit, onboarding, audit wording, and guardrails now expose one stable target-scope contract before moving to close-out only work.

Incremental Delivery

1. Setup and Foundational establish the shared target-scope descriptor and neutral resolution path.
2. Add User Story 1 and validate create and edit neutrality.
3. Add User Story 2 and validate inspection, summary, and status separation parity.
4. Add User Story 3 and validate onboarding reuse, audit wording, and guardrail protection.
5. Finish with formatting, final validation, and close-out documentation.

Parallel Team Strategy

With multiple developers:

1. Complete Setup and Foundational together.
2. After Phase 2:
   • Developer A: create and edit neutrality in apps/platform/app/Filament/Resources/ProviderConnectionResource.php plus supporting mutation wiring.
   • Developer B: list and detail summary alignment in apps/platform/app/Services/Providers/ProviderConnectionStateProjector.php and the new target-scope support files.
   • Developer C: onboarding, audit wording, and guardrails in apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php, apps/platform/tests/Feature/Audit/ProviderConnectionIdentityAuditTest.php, and apps/platform/tests/Feature/Guards/ProviderConnectionNeutralityGuardTest.php.
3. Serialize edits in apps/platform/app/Filament/Resources/ProviderConnectionResource.php because User Stories 1, 2, and 3 all touch that file.

Suggested MVP Scope

The narrowest shippable increment is Phase 1 through Phase 5. Phase 6 is close-out, formatting, and final documentation refresh.

---

Notes

• [P] marks tasks that can run in parallel once their prerequisites are satisfied and the files do not overlap.
• [US1], [US2], and [US3] map directly to the user stories in spec.md.
• The narrowest proving lane remains fast-feedback plus confidence; do not widen into browser or heavy-governance without explicit follow-up justification.
• Keep Microsoft-specific identity contextual and bounded to provider-owned surfaces; do not turn this slice into a second-provider or credential-model redesign.