TenantAtlas/specs/353-provider-connections-resolution-guidance-v1/plan.md

Implementation Plan: Spec 353 - Provider Connections Resolution Guidance v1

• Branch: 353-provider-connections-resolution-guidance-v1
• Date: 2026-06-04
• Spec: specs/353-provider-connections-resolution-guidance-v1/spec.md
• Input: Spec 353 + repo inspection of Provider Connections, Environment Required Permissions, provider verification/permission helpers, and Environment Dashboard provider blocker guidance.

Summary

Add one derived provider-readiness guidance layer to the existing Provider Connections and Required Permissions surfaces, and make the Environment Dashboard provider CTA land on a target page that explains the same blocker clearly.

The implementation stays narrow:

• reuse existing provider connection, permission, capability-group, verification, and last-operation truth
• keep provider actions navigation-first and repo-backed
• preserve onboarding, verification execution, permission calculation, and audit ownership
• avoid live provider calls during render

Technical Context

• Language/Version: PHP 8.4.15, Laravel 12.52.x
• UI stack: Filament 5.2.x, Livewire 4.x
• Database: PostgreSQL, no schema change planned
• Testing: Pest unit + feature/Livewire + one strategic browser smoke
• Validation lanes: fast-feedback + confidence + browser
• Local runtime posture: Sail-first
• Deployment/runtime impact: no expected env, migration, queue-family, scheduler, storage, or panel/provider change
• Global search: unchanged; ProviderConnectionResource remains not globally searchable

Current Repo Truth That Constrains The Slice

• ProviderConnectionResource already exposes provider readiness signals as columns/infolist entries:
  • consent status
  • verification status
  • provider capability
  • last health check
  • last error reason/message
• ViewProviderConnection already keeps one primary Grant admin consent header action and groups the rest under More.
• EditProviderConnection already surfaces View last check run and the existing provider-operation actions, but it is still an action-centered maintenance surface rather than a first-screen readiness-guidance surface.
• EnvironmentRequiredPermissions already renders a summary, capability-group overview, issue cards, copy payloads, and a technical-details section around a native permission matrix.
• ManagedEnvironmentRequiredPermissionsViewModelBuilder already derives:
  • overall readiness (blocked / needs_attention / ready)
  • counts
  • feature impacts
  • capability groups
  • freshness
• EnvironmentDashboardSummaryBuilder already elevates required_permissions / delegated_permissions into operatorGuidance.
• There is no current EnvironmentProviderHealth page class to reuse; provider-health truth is distributed across existing provider/verification helpers.

Domain / Model Implications

• No schema or migration change is planned.
• No new persisted readiness entity, status column, enum family, or provider registry is allowed in this slice.
• The narrowest acceptable implementation shape is one derived provider-guidance adapter over existing ProviderConnectionResolver, ManagedEnvironmentRequiredPermissionsViewModelBuilder, and OperationRun proof truth.
• Existing ownership boundaries remain unchanged:
  • provider connection truth stays provider/resource owned
  • required-permissions truth stays builder/view-model owned
  • verification proof stays OperationRun owned

UI / Filament / Livewire Implications

• Filament v5 continues to run on Livewire v4.x; no version or API drift is permitted.
• No panel/provider registration change is allowed; apps/platform/bootstrap/providers.php remains untouched.
• ProviderConnectionResource stays not globally searchable.
• Existing destructive or high-risk actions must keep their current confirmation, authorization, notification, and audit posture.
• No new asset registration is planned, so there is no expected filament:assets deployment change for this spec.

RBAC / Policy Implications

• Workspace membership and environment entitlement remain the only scope authorities.
• Existing provider capabilities continue to decide whether actions are visible, disabled, or executable.
• Guidance selection itself must remain safe for unauthorized users by operating only on already-authorized page state.

Audit / Logging / Evidence Implications

• Existing provider verification start/result handling and OperationRun proof links are reused unchanged.
• No new audit stream, notification family, or evidence artifact is planned.
• The implementation must keep provider-readiness render paths read-only and side-effect free.

Data / Migration Implications

• No database migration, backfill, or persisted projection is planned.
• All derived readiness output must be request-local and DB-backed from already stored truth.
• Compatibility shims are not justified because no data shape replacement is proposed in this prep slice.

Rollout Considerations

• No feature flag is expected because the slice is a bounded presentation improvement over existing repo truth.
• Staging validation should still prove three operator states explicitly:
  • missing permissions
  • verification follow-up
  • calm ready state
• Production risk is limited to UI guidance hierarchy and wrong-link regressions, so tests and browser smoke remain the main rollout controls.

UI / Surface Guardrail Plan

• Guardrail scope:
  • Provider Connections list and view, plus edit-page action/proof continuity
  • Environment Required Permissions
  • dashboard target continuity only
• Affected surfaces:
  • 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
  • apps/platform/app/Filament/Resources/ProviderConnectionResource/Pages/EditProviderConnection.php
  • apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php
  • apps/platform/resources/views/filament/pages/environment-required-permissions.blade.php
  • apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
• Native vs custom:
  • preserve native Filament list/detail/page ownership
  • avoid new custom page families
  • allow one bounded derived guidance presenter/adapter if necessary
• Shared-family relevance:
  • status messaging
  • next-action guidance
  • operation proof links
  • dashboard-to-detail continuity
• Required tests / smoke:
  • focused unit tests for derived guidance selection
  • feature tests for Provider Connections and Required Permissions
  • one bounded browser smoke for priority and target continuity
• UI/Productization coverage:
  • update ui-009-provider-connections.md
  • create/update ui-077-required-permissions.md
  • close the current UI-audit registry for UI-072/UI-077 in route-inventory.md
  • update design-coverage-matrix.md only if route-inventory counts or classification change
  • update strategic-surfaces.md only if UI-077 is intentionally promoted from its current registry classification
  • use unresolved-pages.md if browser or screenshot evidence cannot be durably stored under the Spec 353 artifact path
  • save screenshots under the Spec 353 artifact path, or document the host-visible artifact blocker honestly

Shared Pattern And System Fit

• Preferred reuse path:
  • current dashboard operatorGuidance structure
  • current ManagedEnvironmentRequiredPermissionsViewModelBuilder truth
  • current ProviderConnectionResolver truth
  • current OperationRunLinks / verification-run start UX
• Likely implementation shape:
  • one bounded derived adapter under a current provider/guidance support path
  • adjacent seams such as ProviderReasonTranslator / VerificationLinkBehavior may stay contextual helpers, but they do not need to become the primary runtime path
• Avoid:
  • new provider framework
  • new persisted readiness state
  • new route/query contract unless absolutely required for continuity

OperationRun UX Impact

Spec 353 does not create a new OperationRun type. It reuses the existing provider verification path:

• StartVerification
• ProviderOperationStartResultPresenter
• OperationRunLinks

Implementation responsibility is limited to when these existing links/actions become the primary or secondary action for a derived blocker.

Likely Runtime Files

Area	Repo-real files
Provider Connections runtime	apps/platform/app/Filament/Resources/ProviderConnectionResource.php, Pages/ListProviderConnections.php, Pages/ViewProviderConnection.php, Pages/EditProviderConnection.php
Required Permissions runtime	apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php, apps/platform/resources/views/filament/pages/environment-required-permissions.blade.php
Permission truth	apps/platform/app/Services/Intune/ManagedEnvironmentRequiredPermissionsViewModelBuilder.php
Provider readiness truth	apps/platform/app/Support/ResolutionGuidance/Adapters/ProviderReadinessResolutionAdapter.php, apps/platform/app/Services/Providers/ProviderConnectionResolver.php, existing OperationRun proof, with ProviderReasonTranslator.php / VerificationLinkBehavior.php only where directly helpful
Dashboard continuity	apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
Links/helpers	apps/platform/app/Support/Links/RequiredPermissionsLinks.php, existing ManagedEnvironmentLinks / OperationRunLinks
UI audit docs	docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md, docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md

Likely Test Files

Layer	Planned file
Unit	apps/platform/tests/Unit/ResolutionGuidance/Spec353ProviderReadinessResolutionAdapterTest.php
Feature	apps/platform/tests/Feature/ProviderConnections/Spec353ProviderConnectionGuidanceTest.php
Feature/Filament	apps/platform/tests/Feature/Filament/Spec353RequiredPermissionsGuidanceTest.php
Browser	apps/platform/tests/Browser/Spec353ProviderReadinessGuidanceSmokeTest.php

Implementation Approach

Phase 0 - Repo Truth Gate

1. Re-read spec.md, plan.md, tasks.md, repo-truth-map.md, checklists/requirements.md, and contracts/provider-readiness-signal-map.md.
2. Re-verify the current runtime truth in the provider/resource/page/helper files listed above.
3. Keep draft mismatches explicit:
   • no EnvironmentProviderHealth.php
   • no existing ui-077-required-permissions.md
4. Confirm no migration, package, env var, queue-family, storage, panel/provider, or global-search change is required.

Phase 1 - Tests First

1. Add unit coverage for deterministic guidance selection:
   • no provider connection
   • disabled/unusable connection
   • missing application permissions
   • missing delegated permissions
   • verification blocked/error
   • verification stale/unknown
   • ready/no urgent action
2. Add feature coverage for Provider Connections:
   • one dominant case
   • one primary action
   • secondary proof links only when repo-backed
   • no fake remediation buttons
3. Add feature coverage for Required Permissions:
   • blocker guidance renders before the raw matrix
   • application/delegated/stale cases map to the expected action hierarchy
   • copy payloads and technical details remain secondary
4. Add one browser smoke:
   • dashboard -> target continuity
   • permissions-missing state
   • verification follow-up state
   • calm ready state

Phase 2 - Derived Guidance Contract

1. Choose the narrowest implementation shape:
   • prefer one bounded provider-guidance adapter/presenter
   • avoid broadening ReviewPackOutputResolutionAdapter into a provider super-framework
2. Build one derived provider-readiness payload with:
   • key
   • title
   • status
   • tone
   • reason
   • impact
   • primary action
   • secondary actions
   • details
   • source metadata
3. Consume only stored truth:
   • ProviderConnection state
   • permission counts and capability groups
   • freshness
   • last provider.connection.check run
   • reason translation / next-step mapping
4. Keep priority ordering explicit and narrow.

Phase 3 - Provider Connections Integration

1. Add a top guidance presentation to Provider Connections list/view without removing the existing table columns, infolist truth, or safe action groups.
2. Reuse existing repo-backed targets:
   • Grant admin consent
   • View last check run
   • Run verification
   • Open required permissions
3. Keep destructive/high-impact actions unchanged:
   • confirmation
   • authorization
   • audit
   • notifications
4. Do not enable provider actions merely because guidance makes them more visible.

Phase 4 - Required Permissions Integration

1. Replace the current guidance-first-but-generic summary with one explicit blocker case.
2. Reuse the current capability-group and counts truth before inventing any new provider state.
3. Keep copy payloads and the raw matrix secondary.
4. If verification or last-operation proof is stronger than the raw permission count, the page may surface that as the primary blocker only when repo truth clearly supports it.

Phase 5 - Dashboard Target Continuity

1. Keep the Environment Dashboard provider guidance selection logic narrow.
2. Adjust continuity only if required so the linked target surface shows the same blocker class clearly.
3. Avoid adding a fragile dashboard-only query contract when current route state is enough.

Phase 6 - Copy, Audit, And Browser Proof

1. Update or add only the copy required for:
   • provider readiness blocked
   • required permissions missing
   • provider verification required
   • provider verification failed
   • provider connection ready
2. Update ui-009-provider-connections.md.
3. Create/update ui-077-required-permissions.md.
4. Close the UI-audit registry around UI-072/UI-077:
   • update route-inventory.md report/screenshot references
   • update design-coverage-matrix.md only if classification/counts change
   • update strategic-surfaces.md only if UI-077 is intentionally promoted from its current registry classification
   • use unresolved-pages.md if browser evidence cannot be durably stored
5. Save screenshots under specs/353-provider-connections-resolution-guidance-v1/artifacts/screenshots/ or record the container-local artifact blocker explicitly during close-out if Pest Browser cannot persist host-visible files.

Test Strategy

• Unit:
  • deterministic blocker ranking and payload mapping
• Feature/Livewire:
  • Provider Connections list/detail integration
  • Required Permissions page integration
  • dashboard target continuity if feature-level proof is cheaper than browser-only proof
• Browser:
  • one small smoke proving real hierarchy and continuity on the rendered UI
• Render-path guard:
  • fail if provider guidance rendering pulls live provider or Graph work into the page request

Risk Controls

• Onboarding overlap: preserve onboarding links as secondary and do not rewrite onboarding ownership.
• UI overload: keep one dominant case and collapse technical detail.
• Fake remediation: do not add unsupported buttons or pretend provider fixes can happen inline.
• Render-time remote calls: limit inputs to existing DB-backed/provider-state helpers only.
• Audit coverage drift: keep existing provider action audit posture unchanged and document any unavoidable copy-only discrepancy.

Constitution Check

• Inventory-first / stored-truth-first: PASS
• Read/write separation: PASS
• No live provider calls during render: PASS target
• Workspace/environment isolation: PASS target
• Shared pattern first: PASS if current dashboard/operator-guidance shape is reused
• Provider boundary neutrality: PASS if shared copy stays provider-neutral and details keep provider-specific labels
• UI/Productization coverage: PASS once ui-009, ui-077, and the required UI-audit registry close-out around UI-072/UI-077 are handled
• Test governance: PASS with explicit Unit + Feature + Browser split
• Proportionality / anti-bloat: PASS if the guidance layer remains derived-only and no new persisted truth or framework is added

Open Questions

• None blocking prep readiness. The main repo-truth caveat is the missing existing ui-077-required-permissions.md, which is handled as a create-during-implementation requirement rather than an unresolved product decision.