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

# Implementation Plan: Provider Capability Registry

**Branch**: `283-provider-capability-registry` | **Date**: 2026-05-08 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `specs/283-provider-capability-registry/spec.md`

## Summary

Prepare the next reserved provider-boundary slice by introducing one provider capability registry and derived capability-evaluation path over the repo's existing provider connection, required-permissions, onboarding, blocked-operation, and support-diagnostic seams. The narrow implementation path reuses the current provider operation registry, provider operation start gate, required-permissions matrix, provider reason translation, provider-connections resource, onboarding wizard, and support links while explicitly rejecting a provider-capability table, a provider framework, a user RBAC rewrite, a broader taxonomy, and adjacent cutover work from Specs `284` through `287`.

This plan is intentionally bounded. Filament remains v5 on Livewire v4, provider registration remains in `apps/platform/bootstrap/providers.php`, `ProviderConnectionResource` remains non-globally-searchable, existing destructive provider-connection actions stay confirmation-protected and server-authorized, and raw Graph permission names remain provider-owned evidence rather than the new primary operator vocabulary.

## Inherited Baseline / Explicit Delta

### Inherited baseline

- Spec `279` already completed the managed-environment core cutover and is historical prerequisite context only.
- Spec `280` already prepared the workspace-first shell and remains separate adjacent context only.
- Spec `281` already prepared the provider-neutral target-scope and provider-identity baseline and is an implementation prerequisite for `283`.
- `apps/platform/app/Filament/Resources/ProviderConnectionResource.php` already exists with `List`, `Create`, `View`, and `Edit` pages, remains `protected static bool $isGloballySearchable = false;`, and already groups mutating actions behind confirmation-protected Filament actions.
- `apps/platform/app/Filament/Pages/TenantRequiredPermissions.php` already lives under the workspace-first managed-environment route shell and already keeps its actions inside the page body rather than the page header.
- `apps/platform/app/Support/Verification/TenantPermissionCheckClusters.php` already groups raw permission rows into diagnostic clusters such as admin consent, directory/groups, Intune configuration, apps, RBAC, and scripts, but it does not yet publish workflow capability truth.
- `apps/platform/app/Services/Providers/ProviderOperationRegistry.php` already maps operation types to user RBAC capability requirements and provider bindings, but it does not yet map those operations to provider application capabilities.
- `apps/platform/app/Services/Providers/ProviderOperationStartGate.php` already blocks or starts provider-backed work through one shared path, but it still explains missing prerequisites through reason codes and raw requirement detail rather than a stable capability contract.
- `apps/platform/app/Support/Providers/ProviderReasonTranslator.php`, contextual-help catalog or resolver seams, and support-diagnostic consumers already translate provider blockers and route operators to `RequiredPermissionsLinks`, but they still lead with provider-specific requirement language in several cases.
- `apps/platform/app/Models/ProviderConnection.php` already persists consent state, verification state, `scopes_granted`, and metadata, so `283` must treat provider capability state as derived truth rather than add another table.

### Explicit delta in this plan

- Introduce one bounded provider capability definition and evaluation layer over the existing provider connection, required-permissions, and blocked-operation seams.
- Keep provider capability state derived and request-time or snapshot-derived; do not add a provider-capability table or ledger.
- Map the current provider-backed operation types to explicit provider capability keys.
- Reuse the required-permissions page as the canonical diagnostic deep dive, but group or summarize raw requirement rows under shared capability headings and statuses.
- Reuse `ProviderConnectionResource` and `ManagedTenantOnboardingWizard` as the operator-facing summary consumers for the new capability contract.
- Reuse `ProviderReasonTranslator`, `ProviderNextStepsRegistry`, and existing support or product-knowledge links so blocked-operation and diagnostic guidance adopts the same capability vocabulary.
- Keep raw Graph permission names, Intune RBAC prerequisite detail, consent links, and provider portal metadata nested inside provider-owned remediation or evidence blocks.
- Keep Specs `284` through `287` explicitly deferred.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52  
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, existing provider operation, provider reason, onboarding, and required-permissions seams  
**Storage**: PostgreSQL, no new persistence or schema change in this slice  
**Testing**: Pest unit tests, Pest feature tests, and one Pest browser smoke  
**Validation Lanes**: fast-feedback, confidence, browser  
**Target Platform**: Laravel monolith in `apps/platform`  
**Project Type**: web application  
**Performance Goals**: preserve current provider-connection, onboarding, and required-permissions responsiveness while changing only derived capability evaluation and summary presentation; no new remote inline work or asset path is introduced  
**Constraints**: no provider-capability table, no provider framework, no user RBAC changes, no route-cutover work from Spec `280`, no provider-identity extraction work from Spec `281`, provider registration stays in `apps/platform/bootstrap/providers.php`, and `ProviderConnectionResource` stays non-globally-searchable  
**Scale/Scope**: one shared capability contract over the existing Microsoft provider implementation and current provider-backed workflows only

## Likely Affected Repo Surfaces

- `apps/platform/app/Services/Providers/ProviderOperationRegistry.php`
- `apps/platform/app/Services/Providers/ProviderOperationStartGate.php`
- `apps/platform/app/Support/Providers/ProviderReasonCodes.php`
- `apps/platform/app/Support/Providers/ProviderReasonTranslator.php`
- `apps/platform/app/Support/Providers/ProviderNextStepsRegistry.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/Providers/TargetScope/ProviderConnectionSurfaceSummary.php`
- `apps/platform/app/Support/Links/RequiredPermissionsLinks.php`
- `apps/platform/app/Support/ProductKnowledge/ContextualHelpCatalog.php`
- `apps/platform/app/Support/ProductKnowledge/ContextualHelpResolver.php`
- `apps/platform/app/Support/TenantDashboard/TenantDashboardSummaryBuilder.php` if that surface already consumes the shared provider prerequisite explanation and must stay aligned without becoming a separate dashboard initiative
- `apps/platform/config/provider_boundaries.php`
- `apps/platform/config/intune_permissions.php` only if the implementation needs to read existing provider-owned requirement identifiers from the current config rather than re-declare them locally
- new bounded support files under `apps/platform/app/Support/Providers/Capabilities/` only if implementation needs a small dedicated namespace for the registry, status enum, and evaluator
- representative proof files under `apps/platform/tests/Unit/Providers/`, `apps/platform/tests/Unit/Verification/`, `apps/platform/tests/Feature/Providers/`, `apps/platform/tests/Feature/Filament/`, `apps/platform/tests/Feature/Onboarding/`, `apps/platform/tests/Feature/RequiredPermissions/`, `apps/platform/tests/Feature/SupportDiagnostics/`, and `apps/platform/tests/Browser/`

## Filament v5 / Capability Surface Notes

- **Livewire v4.0+ compliance**: all touched Filament work remains on Filament v5 with Livewire v4.
- **Provider registration location**: provider registration stays in `apps/platform/bootstrap/providers.php`; nothing moves to `bootstrap/app.php`.
- **Global search rule**: `ProviderConnectionResource` remains non-globally-searchable and keeps its `View` and `Edit` pages. No new searchable resource is introduced by this slice.
- **Destructive actions**: touched provider-connection mutations keep the existing `->action(...)`, `->requiresConfirmation()`, and server-authorization contracts. `Grant admin consent` remains navigation-only.
- **Asset strategy**: no new asset registration or deploy-step change is planned.

## Provider Capability Contract Fit

- Introduce one bounded capability definition source for current-release provider-backed workflows only.
- Keep the shared capability-key inventory limited to the workflows already present in repo truth:
  - `provider_connection_check`
  - `inventory_read`
  - `configuration_read`
  - `restore_execute`
  - `directory_groups_read`
  - `directory_role_definitions_read`
- Keep capability status values limited to the derived family from the spec: `supported`, `missing`, `blocked`, `unknown`, and `not_applicable`.
- Keep capability definitions platform-core, but keep provider requirement mappings provider-owned. That means capability definitions can point to provider-owned requirement keys such as cluster identifiers or Graph permission names without promoting those raw identifiers into the top-level operator vocabulary.
- Prefer one small code-first registry plus evaluator namespace over a new config-first framework or a new table. If implementation discovers that one small code-first registry cannot stay reviewable, that change must be re-justified rather than added silently.
- Reuse existing permission-cluster evidence and provider-connection state as inputs. The capability layer should not replace those inputs; it should standardize how they are interpreted by workflow consumers.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed surfaces
- **Native vs custom classification summary**: mixed native Filament resource plus existing custom onboarding wizard
- **Shared-family relevance**: provider summary, blocked guidance, onboarding readiness, required-permissions diagnostics, support translation
- **State layers in scope**: page, detail, modal, Livewire state, URL-query
- **Audience modes in scope**: operator-MSP, support-platform
- **Decision/diagnostic/raw hierarchy plan**: capability-first summary, diagnostics-second evidence, provider-raw-third remediation detail
- **Raw/support gating plan**: provider-specific requirement detail stays nested or lower-priority; raw permission rows stay on the diagnostic page rather than the top-level summary
- **One-primary-action / duplicate-truth control**: provider-connections and onboarding surface one dominant next step from the capability result and delegate the full proof to the required-permissions page
- **Handling modes by drift class or surface**: review-mandatory
- **Repository-signal treatment**: review-mandatory until provider-connections, onboarding, required-permissions, and blocked-operation messaging all use the same capability labels
- **Special surface test profiles**: standard-native-filament, workflow-hub, shared-detail-family
- **Required tests or browser smoke**: functional-core, state-contract, browser-smoke
- **Exception path and spread control**: none; the slice removes explanation drift rather than adding a new exception
- **Active feature PR close-out entry**: Guardrail

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes
- **Systems touched**: provider operation registry, provider operation start gate, required-permissions diagnostics, onboarding readiness, provider connection summaries, provider reason translation, contextual help, and support-diagnostic guidance
- **Shared abstractions reused**: `ProviderOperationRegistry`, `ProviderOperationStartGate`, `ProviderReasonTranslator`, `ProviderNextStepsRegistry`, `TenantPermissionCheckClusters`, `TenantRequiredPermissionsViewModelBuilder`, `ProviderConnectionSurfaceSummary`, and `RequiredPermissionsLinks`
- **New abstraction introduced? why?**: one small registry plus evaluator namespace is expected because multiple existing shared consumers need one stable capability contract and no current shared abstraction owns that concept yet
- **Why the existing abstraction was sufficient or insufficient**: existing abstractions already own provider connection state, permission evidence, or blocked-operation explanation, but none of them own the workflow-capability concept across all current consumers
- **Bounded deviation / spread control**: provider-owned Graph permission names, Intune RBAC detail, consent links, and portal metadata remain nested evidence only and must not define the shared capability contract

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: yes
- **Central contract reused**: `ProviderOperationStartGate`, `ProviderOperationStartResultPresenter`, `OperationUxPresenter`, and the current `OperationRunService` lifecycle path
- **Delegated UX behaviors**: blocked-versus-started behavior, queued intent messaging, run links, capability-driven remediation hints, and provider-safe follow-up routing stay delegated to the existing shared provider-operation path
- **Surface-owned behavior kept local**: `ProviderConnectionResource` and `ManagedTenantOnboardingWizard` keep only initiation affordances, summary placement, and assist entry points
- **Queued DB-notification policy**: `N/A`
- **Terminal notification path**: existing central lifecycle mechanism
- **Exception path**: none

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: yes
- **Provider-owned seams**: raw Graph permission names, Intune RBAC remediation detail, admin-consent links, required-permissions URLs, portal links, and any provider-specific troubleshooting metadata
- **Platform-core seams**: capability definitions, capability status evaluation, operation-to-capability mapping, blocked-operation capability summary, shared capability labels, and shared diagnostic grouping
- **Neutral platform terms / contracts preserved**: `provider capability`, `capability key`, `capability status`, `provider connection`, `managed environment`, `target workflow`, and `provider requirement`
- **Retained provider-specific semantics and why**: the current Microsoft provider still needs its own raw permission names, consent guidance, and Intune RBAC detail for operators to fix blockers. Those details remain explicit provider-owned evidence.
- **Bounded extraction or follow-up path**: no broader taxonomy or multi-provider framework work in this slice; that remains with Specs `284` through `287`

## Constitution Check

*GATE: Must pass before implementation begins and again after design artifacts are complete.*

- Inventory-first / snapshot truth: PASS. The slice derives capability truth from existing provider and permission evidence.
- Read/write separation: PASS. No new remote-write workflow is introduced.
- Graph contract path: PASS. No new Graph endpoint or contract-registry work is added.
- Deterministic capabilities: PASS with implementation condition. Capability evaluation must be testable and deterministic from the existing provider and permission inputs.
- RBAC-UX plane separation: PASS. `/admin` versus `/system` remains unchanged.
- Workspace isolation: PASS. Workspace membership remains the first boundary.
- Managed-environment isolation: PASS. Managed-environment entitlement remains the second boundary.
- Destructive action discipline: PASS by preservation. Existing confirmation-protected provider-connection mutations remain unchanged.
- Global search safety: PASS. `ProviderConnectionResource` stays non-globally-searchable.
- OperationRun / Ops-UX: PASS. The slice reuses the shared provider-operation start path and changes only its prerequisite contract.
- Data minimization: PASS. No new persistence or provider-capability ledger is introduced.
- Test governance: PASS. Proof stays bounded to unit, feature, and one browser smoke.
- Proportionality / no premature abstraction: PASS with implementation condition. Any new support namespace must stay narrow and current-release only.
- Persisted truth / behavioral state: PASS. One new derived state family is introduced; no new persistence is introduced.
- UI semantics / shared pattern first / Filament-native UI: PASS. Existing resource, page, and wizard surfaces remain the primary operator paths.
- Provider boundary: PASS with implementation condition. Raw provider requirement detail must remain secondary evidence rather than reappearing as the primary shared label set.

**Gate evaluation**: PASS.

**Post-design re-check**: PASS while `research.md`, `data-model.md`, `quickstart.md`, `contracts/provider-capability-registry.logical.openapi.yaml`, and `checklists/requirements.md` stay aligned on the same capability keys, status family, derived-truth posture, and proof commands.

## Test Governance Check

- **Test purpose / classification by changed surface**: Unit, Feature, Browser
- **Affected validation lanes**: fast-feedback, confidence, browser
- **Why this lane mix is the narrowest sufficient proof**: the registry and evaluator logic are pure derivation and deserve unit proof; the shared start gate, provider-connections, onboarding, required-permissions page, and support translation need feature proof; one browser smoke is enough to prove the real operator path from provider connection or onboarding into the diagnostic page
- **Narrowest proving command(s)**:
  - `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)`
  - `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)`
  - `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)`
  - `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)`
- **Fixture / helper / factory / seed / context cost risks**: moderate because proof needs workspace, managed environment, provider connection, permission evidence, and blocked-operation context without widening shared fixture defaults
- **Expensive defaults or shared helper growth introduced?**: no; any new capability test helper should stay feature-local and opt-in
- **Heavy-family additions, promotions, or visibility changes**: none beyond one bounded browser smoke
- **Surface-class relief / special coverage rule**: standard-native-filament relief for provider-connections and required-permissions; one workflow-hub smoke for onboarding continuity
- **Closing validation and reviewer handoff**: rerun the commands above, verify that no provider-capability table appears, verify that the registry stays current-release-only, verify that provider-connections and onboarding use the same capability labels, verify that the required-permissions page groups evidence under those same labels, verify that blocked-operation context carries capability information, and verify that raw Graph permission names remain secondary evidence
- **Budget / baseline / trend follow-up**: contained feature-local increase only
- **Review-stop questions**: did the implementation add persistence, did it invent future-facing capability keys, did it widen into RBAC or taxonomy work, did any touched surface keep a page-local permission vocabulary, did blocked-operation context stay on reason-only or raw permission language
- **Escalation path**: `reject-or-split` if implementation introduces persistence, a provider framework, a user RBAC rewrite, or broader cutover work from adjacent specs
- **Active feature PR close-out entry**: Guardrail
- **Why no dedicated follow-up spec is needed**: adjacent follow-up work already exists as Specs `284` through `287`; `283` only needs the bounded capability slice itself

## Review Checklist Status

- **Review checklist artifact**: `checklists/requirements.md`
- **Review outcome class**: `implementation-ready`
- **Workflow outcome**: `keep`
- **Test-governance outcome**: `keep`
- **Escalation rule**: if implementation adds persistence, broad future-facing keys, or adjacent-spec scope, flip the workflow outcome to `split` or `reject-or-split`

## Rollout Considerations

- Land the registry definitions, evaluator, and shared consumer updates as one bounded slice so provider-connections, onboarding, required-permissions diagnostics, and provider-operation blocking all converge atomically.
- Update the shared evaluation and translation seams before polishing page copy so the touched surfaces inherit the same contract rather than reformatting raw evidence separately.
- Keep provider-owned evidence and remediation nested from the start; otherwise the later UI pass will still have to untangle raw Microsoft-first summaries.
- Keep dashboard or support surfaces limited to consumers of the shared capability contract and do not let them grow into a separate productization initiative in this slice.

## Risk Controls

- Reject any implementation that introduces a provider-capability table, ledger, or snapshot model.
- Reject any implementation that creates a future-facing provider framework or tries to solve multi-provider routing, taxonomy, or UI copy in the same slice.
- Reject any implementation that leaves provider-connections, onboarding, and required-permissions diagnostics on different capability or requirement vocabularies.
- Reject any implementation that collapses user RBAC capability failures into provider application capability failures.
- Reject any implementation that promotes raw Graph permission names back into the primary operator summary on touched surfaces.

## Research & Design Outputs

- `research.md` records the bounded derivation decisions, the capability-key inventory, the provider-owned evidence rules, and the rejected alternatives.
- `data-model.md` captures the derived capability definition, result, evidence, grouped diagnostic view, and operation-gate contracts.
- `quickstart.md` gives reviewers the bounded proof flow and exact commands.
- `contracts/provider-capability-registry.logical.openapi.yaml` models the logical capability summary, diagnostic grouping, onboarding assist, support explanation, and operation-start contract.
- `checklists/requirements.md` records package readiness, boundedness, and outcome state.

## Project Structure

### Documentation (this feature)

```text
specs/283-provider-capability-registry/
├── checklists/
│   └── requirements.md
├── contracts/
│   └── provider-capability-registry.logical.openapi.yaml
├── data-model.md
├── plan.md
├── quickstart.md
├── research.md
├── spec.md
└── tasks.md
```

### Source Code (expected implementation surfaces)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   ├── Pages/
│   │   │   ├── TenantRequiredPermissions.php
│   │   │   └── Workspaces/
│   │   │       └── ManagedTenantOnboardingWizard.php
│   │   └── Resources/
│   │       └── ProviderConnectionResource.php
│   ├── Models/
│   │   └── ProviderConnection.php
│   ├── Services/
│   │   ├── Intune/
│   │   │   └── TenantRequiredPermissionsViewModelBuilder.php
│   │   └── Providers/
│   │       ├── ProviderOperationRegistry.php
│   │       └── ProviderOperationStartGate.php
│   └── Support/
│       ├── Links/
│       │   └── RequiredPermissionsLinks.php
│       ├── ProductKnowledge/
│       │   ├── ContextualHelpCatalog.php
│       │   └── ContextualHelpResolver.php
│       ├── Providers/
│       │   ├── ProviderNextStepsRegistry.php
│       │   ├── ProviderReasonCodes.php
│       │   ├── ProviderReasonTranslator.php
│       │   ├── TargetScope/
│       │   │   └── ProviderConnectionSurfaceSummary.php
│       │   └── Capabilities/
│       │       ├── ProviderCapabilityRegistry.php
│       │       ├── ProviderCapabilityResult.php
│       │       ├── ProviderCapabilityStatus.php
│       │       └── ProviderCapabilityEvaluator.php
│       ├── TenantDashboard/
│       │   └── TenantDashboardSummaryBuilder.php
│       └── Verification/
│           └── TenantPermissionCheckClusters.php
├── config/
│   ├── intune_permissions.php
│   └── provider_boundaries.php
└── tests/
    ├── Browser/
    │   └── Spec283ProviderCapabilityRegistrySmokeTest.php
    ├── Feature/
    │   ├── Filament/
    │   │   └── ProviderConnectionCapabilitySummaryTest.php
    │   ├── Onboarding/
    │   │   └── ManagedTenantOnboardingCapabilityAssistTest.php
    │   ├── Providers/
    │   │   ├── ProviderCapabilityEvaluationTest.php
    │   │   └── ProviderOperationCapabilityGateTest.php
    │   ├── RequiredPermissions/
    │   │   └── RequiredPermissionsCapabilityGroupingTest.php
    │   └── SupportDiagnostics/
    │       └── ProviderCapabilityReasonTranslationTest.php
    └── Unit/
        ├── Providers/
        │   └── ProviderCapabilityRegistryTest.php
        └── Verification/
            └── TenantPermissionCapabilityMappingTest.php
```

**Structure Decision**: keep the implementation inside `apps/platform` and add only one small support namespace for provider capability definitions and derived evaluation. Reuse existing Filament, provider-operation, required-permissions, and support-diagnostic seams instead of creating a new module or package.