TenantAtlas/specs/283-provider-capability-registry/tasks.md

description
Task list for Provider Capability Registry

Tasks: Provider Capability Registry

Input: Design documents from specs/283-provider-capability-registry/
Prerequisites: specs/283-provider-capability-registry/spec.md, specs/283-provider-capability-registry/plan.md, specs/283-provider-capability-registry/checklists/requirements.md, specs/283-provider-capability-registry/research.md, specs/283-provider-capability-registry/data-model.md, specs/283-provider-capability-registry/quickstart.md, and specs/283-provider-capability-registry/contracts/provider-capability-registry.logical.openapi.yaml
Implementation Posture: Runtime implementation complete. Targeted unit, feature, browser smoke, and dirty-file formatting validation passed in the implementation loop.
Tests: REQUIRED (Pest). Keep proof bounded to apps/platform/tests/Unit/Providers/ProviderCapabilityRegistryTest.php, apps/platform/tests/Unit/Verification/TenantPermissionCapabilityMappingTest.php, apps/platform/tests/Feature/Providers/ProviderCapabilityEvaluationTest.php, apps/platform/tests/Feature/Providers/ProviderOperationCapabilityGateTest.php, apps/platform/tests/Feature/Filament/ProviderConnectionCapabilitySummaryTest.php, apps/platform/tests/Feature/Onboarding/ManagedTenantOnboardingCapabilityAssistTest.php, apps/platform/tests/Feature/RequiredPermissions/RequiredPermissionsCapabilityGroupingTest.php, apps/platform/tests/Feature/SupportDiagnostics/ProviderCapabilityReasonTranslationTest.php, and apps/platform/tests/Browser/Spec283ProviderCapabilityRegistrySmokeTest.php.
Operations: No new OperationRun family. Reuse apps/platform/app/Services/Providers/ProviderOperationStartGate.php, the existing ProviderOperationStartResultPresenter path, OperationUxPresenter, and the current OperationRunService lifecycle ownership. This slice only adds a shared provider capability prerequisite contract over that existing provider-operation path.
RBAC: Workspace membership remains the first 404 boundary, managed-environment access remains the second 404 boundary, and current user capability denials such as PROVIDER_VIEW, PROVIDER_MANAGE, PROVIDER_MANAGE_DEDICATED, PROVIDER_RUN, TENANT_MANAGE, and TENANT_SYNC remain 403. Provider application capability failures remain a distinct derived result and must not be folded into user RBAC.
Shared Pattern Reuse: Reuse ProviderOperationRegistry, ProviderOperationStartGate, ProviderReasonTranslator, ProviderNextStepsRegistry, TenantPermissionCheckClusters, TenantRequiredPermissionsViewModelBuilder, ProviderConnectionSurfaceSummary, ProviderConnectionResource, TenantRequiredPermissions, ManagedTenantOnboardingWizard, RequiredPermissionsLinks, and the current contextual-help or support-diagnostic seams. Do not introduce a provider-capability table, a provider framework, a broader taxonomy, a user RBAC rewrite, route cutover work, copy-neutralization work, or adjacent Spec 284 through 287 scope.
Filament / Panel Guardrails: Filament remains v5 on Livewire v4. Provider registration remains in apps/platform/bootstrap/providers.php. ProviderConnectionResource remains non-globally-searchable while keeping View and Edit pages. Any touched destructive action must continue to use ->action(...), ->requiresConfirmation(), and current server authorization. Asset strategy stays unchanged.
Compatibility Posture: Reject provider-capability persistence, future-facing capability inventories, shared raw Graph permission names as primary vocabulary, user RBAC or route-shell rewrites, and keep Specs 284 through 287 deferred.
External Prerequisite: Spec 281 provider-connection-scope groundwork must already be merged or otherwise present on the implementation branch before any runtime or test task starts.
Organization: Tasks are grouped by user story so provider-connection summary truth, provider-operation capability gating, onboarding and required-permissions convergence, and support-diagnostic consistency remain independently testable.
Review Outcome: implementation-ready
Workflow Outcome: keep
Test-governance Outcome: keep

Test Governance Checklist

• Lane assignment stays fast-feedback, confidence, and one narrow browser lane.
• New or changed tests stay in the named unit, feature, and browser files only.
• Workspace, managed-environment, provider-connection, and permission-evidence fixtures remain explicit and opt-in; no hidden shared defaults or provider-capability persistence is planned.
• Planned validation commands match spec.md, plan.md, and quickstart.md exactly.
• standard-native-filament, workflow-hub, and shared provider-operation expectations stay explicit for touched surfaces.
• Any attempt to absorb Specs 284 through 287 resolves as split or reject-or-split, not hidden follow-up inside 283.

Canonical Initial Capability Inventory

• provider_connection_check -> provider.connection.check
• inventory_read -> inventory.sync
• configuration_read -> compliance.snapshot
• restore_execute -> restore.execute
• directory_groups_read -> directory.groups.sync
• directory_role_definitions_read -> directory.role_definitions.sync

This bounded inventory is authoritative for Spec 283 tasks and must not widen into future-facing capability keys during implementation.

Phase 0: External Gate

Purpose: Confirm the provider-boundary prerequisite from Spec 281 is available before implementation begins.

• T000 Confirm Spec 281 is already merged or otherwise present on the implementation branch before any runtime or test task begins.

---

Phase 1: Setup (Shared Context)

Purpose: Confirm the bounded provider-capability inventory, proof files, and deferred-scope posture before runtime edits begin.

• T001 Review specs/283-provider-capability-registry/spec.md, plan.md, checklists/requirements.md, research.md, data-model.md, quickstart.md, and contracts/provider-capability-registry.logical.openapi.yaml together so implementation stays on Spec 283 only.
• T002 [P] Confirm the current provider-connection and Filament guardrail seams in apps/platform/app/Models/ProviderConnection.php, apps/platform/app/Filament/Resources/ProviderConnectionResource.php, apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php, apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ViewProviderConnection.php, and apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/EditProviderConnection.php before changing shared summaries.
• T003 [P] Confirm the current provider-operation seams in apps/platform/app/Services/Providers/ProviderOperationRegistry.php, apps/platform/app/Services/Providers/ProviderOperationStartGate.php, and any cooperating presenter or result classes that already own blocked-versus-started feedback.
• T004 [P] Confirm the current required-permissions and verification seams in apps/platform/app/Support/Verification/TenantPermissionCheckClusters.php, apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php, and apps/platform/app/Filament/Pages/TenantRequiredPermissions.php before changing diagnostic grouping.
• T005 [P] Confirm the current onboarding and supporting-link seams in apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php, apps/platform/app/Support/Links/RequiredPermissionsLinks.php, and apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php before capability summaries are introduced.
• T006 [P] Confirm the current provider reason, help, and boundary seams in apps/platform/app/Support/Providers/ProviderReasonTranslator.php, apps/platform/app/Support/Providers/ProviderNextStepsRegistry.php, apps/platform/app/Support/ProductKnowledge/ContextualHelpCatalog.php, apps/platform/app/Support/ProductKnowledge/ContextualHelpResolver.php, apps/platform/config/provider_boundaries.php, and specs/283-provider-capability-registry/checklists/requirements.md so Specs 284 through 287 remain explicitly out of scope.

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the proving suite and the canonical shared capability contract that every story depends on.

Critical: No user-story work should begin until this phase is complete.

• T007 [P] Add failing coverage in apps/platform/tests/Unit/Providers/ProviderCapabilityRegistryTest.php for the initial capability inventory, operator-facing labels, provider-owned requirement mappings, and the bounded current-release key set.
• T008 [P] Add failing coverage in apps/platform/tests/Unit/Verification/TenantPermissionCapabilityMappingTest.php for mapping current permission-cluster evidence into the shared capability contract without promoting raw Graph permission names into the primary vocabulary.
• T009 [P] Add failing coverage in apps/platform/tests/Feature/Providers/ProviderCapabilityEvaluationTest.php for supported, missing, blocked, unknown, and not_applicable capability results derived from existing provider connection and permission evidence.
• T010 [P] Add failing coverage in apps/platform/tests/Feature/Providers/ProviderOperationCapabilityGateTest.php for provider-backed operation types resolving one or more capability keys before the shared start gate allows or blocks the request.
• T011 [P] Add the narrow browser smoke in apps/platform/tests/Browser/Spec283ProviderCapabilityRegistrySmokeTest.php for one provider-connection or onboarding flow into required-permissions diagnostics under the live Filament shell.
• T012 Introduce the bounded shared capability contract in the smallest viable support seam under apps/platform/app/Support/Providers/Capabilities/ and update apps/platform/config/provider_boundaries.php only as needed so later story work consumes one canonical capability definition and evaluation path without reopening Specs 284 through 287.

Checkpoint: The proving files exist, the provider-capability contract is explicit, and later stories can reuse one canonical shared capability definition and evaluation path.

---

Phase 3: User Story 1 - Inspect a provider connection with one capability-first summary (Priority: P1)

Goal: Provider-connections list and detail surfaces tell the operator which workflows the current connection supports without forcing raw provider requirements to become the first explanation layer.

Independent Test: Open the provider-connections list and one connection detail page for a managed environment, then confirm the default-visible summary shows the relevant workflow capability, its status, and one next step while raw provider evidence stays secondary.

Tests for User Story 1

• T013 [P] [US1] Extend apps/platform/tests/Feature/Filament/ProviderConnectionCapabilitySummaryTest.php after T012 to prove ProviderConnectionResource list, view, and edit-adjacent summary surfaces show the shared capability label, capability status, and next step first while keeping raw provider detail nested and preserving workspace or managed-environment 404 versus in-scope capability 403 behavior.
• T014 [P] [US1] Extend apps/platform/tests/Feature/Providers/ProviderCapabilityEvaluationTest.php after T012 to prove the same provider connection produces the same capability result for provider-connections summary consumers and later shared consumers.

Implementation for User Story 1

• T015 [US1] Update the new capability registry and evaluator seam plus apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php so provider-connection summary adapters can ask for shared capability results without reformatting raw evidence locally.
• T016 [US1] Update apps/platform/app/Filament/Resources/ProviderConnectionResource.php, apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php, apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/ViewProviderConnection.php, and apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/EditProviderConnection.php so provider-connections surfaces converge on the shared capability-first summary while preserving non-global-search posture and existing confirmation-protected destructive actions.

Checkpoint: Provider-connections list and detail surfaces now tell one capability-first story before any raw provider requirement detail is disclosed.

---

Phase 4: User Story 2 - Start provider work with the same capability contract (Priority: P1)

Goal: Provider-backed operations start or block using the same capability keys and status semantics shown on provider-connections and later onboarding or diagnostics surfaces.

Independent Test: Trigger one blocked provider-backed action and one allowed provider-backed action, then confirm the start result and any resulting run context use the shared capability contract instead of raw provider requirement names as the primary explanation.

Tests for User Story 2

• T017 [P] [US2] Extend apps/platform/tests/Feature/Providers/ProviderOperationCapabilityGateTest.php after T012 to prove blocked and allowed provider-backed operations evaluate shared capability keys before dispatch, carry the resulting capability context through the shared start path, and keep existing user RBAC denials distinct from provider capability blockers.
• T018 [P] [US2] Extend apps/platform/tests/Feature/SupportDiagnostics/ProviderCapabilityReasonTranslationTest.php after T012 to prove missing-permission or blocked-operation translations adopt the same capability vocabulary as the start-gate result.

Implementation for User Story 2

• T019 [US2] Update apps/platform/app/Services/Providers/ProviderOperationRegistry.php so current provider-backed operation types map to explicit provider capability keys in addition to the existing user RBAC capability requirements.
• T020 [US2] Update apps/platform/app/Services/Providers/ProviderOperationStartGate.php and any cooperating provider-operation result presenter seams so the shared start path evaluates required provider capability keys, blocks or starts accordingly, and records capability context as shared run metadata.
• T021 [US2] Update apps/platform/app/Support/Providers/ProviderReasonTranslator.php and apps/platform/app/Support/Providers/ProviderNextStepsRegistry.php only where required so blocked-operation guidance names the missing capability first and routes operators to the existing required-permissions path.

Checkpoint: Provider-operation start and blocked flows now carry one capability-first explanation that matches the provider-connections summary contract.

---

Phase 5: User Story 3 - See the same capability truth in onboarding and required permissions (Priority: P2)

Goal: Onboarding readiness and the required-permissions page use the same capability labels and status meanings so operators can move from summary to diagnostic evidence without reinterpreting the blocker.

Independent Test: Open onboarding verification for a managed environment with missing provider prerequisites, then open the required-permissions assist and confirm both surfaces use the same capability label and status while keeping raw permission rows as supporting evidence.

Tests for User Story 3

• T022 [P] [US3] Extend apps/platform/tests/Feature/Onboarding/ManagedTenantOnboardingCapabilityAssistTest.php after T012 to prove onboarding readiness and the capability assist consume the same capability label, status, and next-step contract as other shared consumers while preserving workspace or managed-environment 404 boundaries for out-of-scope actors.
• T023 [P] [US3] Extend apps/platform/tests/Feature/RequiredPermissions/RequiredPermissionsCapabilityGroupingTest.php after T012 to prove the required-permissions page groups or summarizes row-level evidence under the shared capability headings without hiding the raw provider-owned evidence.

Implementation for User Story 3

• T024 [US3] Update apps/platform/app/Support/Verification/TenantPermissionCheckClusters.php and apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php so the required-permissions view model can expose shared capability groups plus nested permission evidence.
• T025 [US3] Update apps/platform/app/Filament/Pages/TenantRequiredPermissions.php so the page header or primary summary stays capability-first while the existing diagnostic matrix remains the canonical deep dive for raw evidence.
• T026 [US3] Update apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and confirm apps/platform/app/Support/Links/RequiredPermissionsLinks.php only changes if necessary so onboarding readiness, assist flows, and supporting links converge on the shared capability contract.

Checkpoint: Onboarding and required-permissions diagnostics now describe the same provider blocker with the same capability vocabulary and evidence hierarchy.

---

Phase 6: User Story 4 - Translate provider blockers consistently in support surfaces (Priority: P3)

Goal: Shared help and support-diagnostic consumers describe provider blockers with the same capability vocabulary used on operator-facing surfaces.

Independent Test: Trigger or simulate one provider blocker caused by missing permissions or degraded provider state, then confirm contextual help and support-diagnostic outputs use the same capability-first explanation as the main surfaces.

Tests for User Story 4

• T027 [P] [US4] Extend apps/platform/tests/Feature/SupportDiagnostics/ProviderCapabilityReasonTranslationTest.php after T012 to prove contextual-help or support-diagnostic consumers use the same capability labels and next-step guidance as provider-connections, onboarding, and operation-start flows.

Implementation for User Story 4

• T028 [US4] Update apps/platform/app/Support/ProductKnowledge/ContextualHelpCatalog.php, apps/platform/app/Support/ProductKnowledge/ContextualHelpResolver.php, and any directly touched provider-diagnostic consumer seams so they use the shared capability contract rather than page-local or raw requirement vocabulary. Note: no catalog/resolver code change was required after review; ProviderReasonTranslator is the active diagnostic seam for provider blockers in this slice.

Checkpoint: Shared help and support-diagnostic outputs now reinforce the same capability-first explanation seen elsewhere.

---

Phase 7: Polish & Cross-Cutting Validation

Purpose: Run the exact bounded proof set, perform the final Filament and provider-boundary review, and confirm the slice stayed inside Spec 283.

• T029 [P] Run 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/Unit/Providers/ProviderCapabilityRegistryTest.php tests/Unit/Verification/TenantPermissionCapabilityMappingTest.php).
• T030 [P] Run 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/ProviderCapabilityEvaluationTest.php tests/Feature/Providers/ProviderOperationCapabilityGateTest.php tests/Feature/Filament/ProviderConnectionCapabilitySummaryTest.php tests/Feature/Onboarding/ManagedTenantOnboardingCapabilityAssistTest.php tests/Feature/RequiredPermissions/RequiredPermissionsCapabilityGroupingTest.php tests/Feature/SupportDiagnostics/ProviderCapabilityReasonTranslationTest.php).
• T031 [P] Run 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/Spec283ProviderCapabilityRegistrySmokeTest.php).
• T032 [P] Run 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).
• T033 [P] Review apps/platform/app/Services/Providers/ProviderOperationRegistry.php, apps/platform/app/Services/Providers/ProviderOperationStartGate.php, apps/platform/app/Support/Providers/ProviderReasonTranslator.php, apps/platform/app/Support/Verification/TenantPermissionCheckClusters.php, apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php, apps/platform/app/Filament/Pages/TenantRequiredPermissions.php, apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php, apps/platform/app/Filament/Resources/ProviderConnectionResource.php, apps/platform/app/Support/Links/RequiredPermissionsLinks.php, apps/platform/config/provider_boundaries.php, and apps/platform/bootstrap/providers.php to confirm Filament v5 or Livewire v4 compliance, unchanged provider registration location, unchanged asset strategy, preserved destructive-action confirmation plus authorization, truthful non-global-search posture, derived-only capability state, and Specs 284 through 287 staying deferred.

---

Dependencies & Execution Order

Phase Dependencies

• Phase 0 (External Gate): no dependencies; complete before implementation starts.
• Phase 1 (Setup): depends on Phase 0.
• Phase 2 (Foundational): depends on Phase 1 and blocks all story work.
• Phase 3 (US1): depends on Phase 2 and establishes the canonical provider-connection capability summary contract.
• Phase 4 (US2): depends on Phase 2 and should ship with or immediately after US1 so provider-operation start results match the provider-connection summary contract.
• Phase 5 (US3): depends on US1 and US2 because onboarding and diagnostics should reuse the final shared capability contract rather than an intermediate one.
• Phase 6 (US4): depends on US2 and US3 so support surfaces inherit the final explanation contract.
• Phase 7 (Polish): depends on all desired user stories being complete.

User Story Dependencies

• US1 (P1): independently testable after Phase 2 and is the first required increment.
• US2 (P1): independently testable after Phase 2, but should ship after or with US1 because the shared start-gate language should match the summary language.
• US3 (P2): independently testable after US1 and US2 and should follow once the shared capability contract is stable.
• US4 (P3): independently testable after US2 and US3 and closes the remaining explanation drift in support surfaces.

Within Each User Story

• Write or extend the listed Pest coverage first and make it fail for the intended gap.
• Apply the smallest shared-seam changes needed to satisfy the story without reopening Specs 284 through 287.
• Re-run the narrowest relevant validation command for that story before moving to the next story.

Parallel Execution Examples

• Setup: T002 through T006 can run in parallel once T000 and T001 set the bounded scope.
• Foundational: T007 through T011 can run in parallel before T012 converges the canonical capability contract.
• US1: T013 and T014 can run in parallel; T015 and T016 should merge serially around the shared summary and Filament resource files.
• US2: T017 and T018 can run in parallel; T019 through T021 should follow serially around the shared provider-operation seams.
• US3: T022 and T023 can run in parallel; T024 through T026 should merge serially around the diagnostic and onboarding surfaces.
• US4: T027 can run alongside related implementation prep, then T028 finalizes shared help and support alignment.
• Polish: T029 through T032 can run in parallel after implementation is complete; T033 should close the bounded-scope review last.

Implementation Strategy

Suggested MVP Scope

• MVP = US1 + US2. Land the shared capability contract first on provider-connections and provider-operation starts so the most visible workflow decisions stop depending on raw provider requirement language.

Incremental Delivery

1. Complete Phase 0, Phase 1, and Phase 2.
2. Deliver US1 so provider-connections exposes one capability-first summary contract.
3. Deliver US2 so blocked and allowed provider-backed workflows use the same capability contract.
4. Deliver US3 so onboarding and required-permissions diagnostics inherit the same summary and evidence hierarchy.
5. Deliver US4 so support and contextual-help surfaces stop drifting from the operator-facing explanation.
6. Finish with the exact validation commands and final bounded-scope review in Phase 7.

Team Strategy

1. Parallelize the failing test work first.
2. Serialize merges around apps/platform/app/Support/Providers/Capabilities/, apps/platform/app/Services/Providers/, apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php, apps/platform/app/Filament/Resources/ProviderConnectionResource.php, and apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php to avoid conflicting contract-shape edits.
3. Reject any implementation branch that introduces persistence, future-facing capability keys, provider frameworks, RBAC redesign, route-shell rewrites, or adjacent-spec cutover work.

Deferred Follow-Ups / Non-Goals

• Spec 284 provider-neutral artifact source or taxonomy work
• Spec 285 workspace-first RBAC and environment-access redesign
• Spec 286 broader UI copy, IA, and localization neutralization
• Spec 287 cutover quality gates and no-legacy enforcement beyond this bounded capability slice