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.