--- 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 - [x] Lane assignment stays `fast-feedback`, `confidence`, and one narrow `browser` lane. - [x] New or changed tests stay in the named unit, feature, and browser files only. - [x] Workspace, managed-environment, provider-connection, and permission-evidence fixtures remain explicit and opt-in; no hidden shared defaults or provider-capability persistence is planned. - [x] Planned validation commands match `spec.md`, `plan.md`, and `quickstart.md` exactly. - [x] `standard-native-filament`, `workflow-hub`, and shared provider-operation expectations stay explicit for touched surfaces. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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. - [x] 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 - [x] 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. - [x] 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 - [x] 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. - [x] 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 - [x] 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. - [x] 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 - [x] 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. - [x] 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. - [x] 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 - [x] 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. - [x] 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 - [x] 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. - [x] 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. - [x] 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 - [x] 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 - [x] 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`. - [x] 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)`. - [x] 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)`. - [x] 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)`. - [x] 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)`. - [x] 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