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

# Tasks: Spec 353 - Provider Connections Resolution Guidance v1

**Input**: `specs/353-provider-connections-resolution-guidance-v1/spec.md`, `plan.md`, `repo-truth-map.md`, `contracts/provider-readiness-signal-map.md`, and `checklists/requirements.md`

**Tests**: Required. This spec changes strategic operator-facing readiness guidance on existing Provider Connections and Required Permissions surfaces.

## Test Governance Checklist

- [x] Lane assignment is explicit and narrow: Unit for guidance selection, Feature/Livewire for rendered integration, Browser for first-screen hierarchy and dashboard target continuity.
- [x] New or changed tests stay in the smallest honest family, and the browser addition is explicit.
- [x] Shared helpers, factories, seeds, and context defaults stay cheap by default.
- [x] Planned validation commands cover the slice without pulling in unrelated lane cost.
- [x] The changed surfaces are explicit strategic/detail surfaces, not a hidden infra-only refactor.
- [x] No new persisted readiness truth, provider framework, or enum family is planned.

## Phase 1: Preparation And Repo Truth

**Purpose**: Keep the implementation bounded to the existing runtime seams and recorded draft-to-repo deviations.

- [x] T001 Re-read `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, `contracts/provider-readiness-signal-map.md`, and `checklists/requirements.md`.
- [x] T002 Re-verify the current runtime truth in:
  - `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/Services/Intune/ManagedEnvironmentRequiredPermissionsViewModelBuilder.php`
  - `apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php`
  - `apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php`
  - `apps/platform/app/Support/Providers/ProviderReasonTranslator.php`
  - `apps/platform/app/Support/Verification/VerificationLinkBehavior.php`
- [x] T003 Re-confirm the draft deviations recorded in `repo-truth-map.md`:
  - no `EnvironmentProviderHealth.php`
  - no existing `ui-077-required-permissions.md`
  - Provider Connections already has primary/safe actions and detail truth
  - Required Permissions already has summary/issues/details scaffolding
- [x] T004 Confirm no migration, package, env var, queue family, scheduler, storage, panel/provider, or global-search change is required; keep Livewire v4 and `apps/platform/bootstrap/providers.php` unchanged.
- [x] T005 Keep `repo-truth-map.md` and `contracts/provider-readiness-signal-map.md` current if runtime inspection proves a narrower or broader safe slice.

## Phase 2: Tests First

**Purpose**: Lock decision hierarchy, scope, and no-fake-action behavior before runtime changes.

- [x] T006 Add `apps/platform/tests/Unit/ResolutionGuidance/Spec353ProviderReadinessResolutionAdapterTest.php`.
- [x] T007 Add unit assertions for `no provider connection`.
- [x] T008 Add unit assertions for `connection disabled or unusable`.
- [x] T009 Add unit assertions for `missing application permissions`.
- [x] T010 Add unit assertions for `missing delegated permissions`.
- [x] T011 Add unit assertions for `verification blocked or failed`.
- [x] T012 Add unit assertions for `verification stale / unknown / not yet trusted`.
- [x] T013 Add unit assertions for `provider ready / no urgent provider action`.
- [x] T014 Add a render-path guard assertion proving the derived guidance selection does not require live provider or Graph calls.
- [x] T015 Add `apps/platform/tests/Feature/ProviderConnections/Spec353ProviderConnectionGuidanceTest.php`.
- [x] T016 Add feature assertions that Provider Connections surfaces show one explicit provider-readiness case with one dominant primary action.
- [x] T017 Add feature assertions that only repo-backed secondary actions are rendered and unsupported auto-fix buttons are absent.
- [x] T018 Add feature assertions that workspace/environment/record scope remains correct for all rendered guidance links.
- [x] T019 Add feature assertions that existing provider detail truth and action groups remain present as secondary context.
- [x] T020 Add `apps/platform/tests/Feature/Filament/Spec353RequiredPermissionsGuidanceTest.php`.
- [x] T021 Add feature assertions that Required Permissions renders the blocker guidance before the raw matrix.
- [x] T022 Add feature assertions that missing application, missing delegated, and stale/unknown cases map to distinct operator-facing guidance.
- [x] T023 Add feature assertions that copy payload flows and technical details remain secondary.
- [x] T024 Add feature assertions that no live provider call is required to render Required Permissions guidance.
- [x] T025 Add a dashboard target continuity assertion in the narrowest honest family (Feature if possible, Browser otherwise).
- [x] T026 Add `apps/platform/tests/Browser/Spec353ProviderReadinessGuidanceSmokeTest.php`.
- [x] T027 Browser Flow A: permissions-missing state on Required Permissions; assert one dominant blocker and one primary action.
- [x] T028 Browser Flow B: provider connection verification-follow-up state; assert operation-proof or verification action continuity.
- [x] T029 Browser Flow C: ready state; assert calm posture and secondary details only.
- [x] T030 Browser Flow D: Environment Dashboard -> provider target continuity; assert matching blocker language and scope.
- [x] T031 Browser Flow E: technical details remain collapsed by default and layout stays readable on a mobile-ish width if fixture support exists.

## Phase 3: Derived Guidance Contract

**Purpose**: Build the narrowest derived readiness payload over existing provider and permission truth.

- [x] T032 Choose the narrowest implementation shape:
  - prefer one bounded provider-readiness adapter/presenter
  - avoid broadening `ReviewPackOutputResolutionAdapter` into a provider meta-framework
- [x] T033 Consume existing signals from `ProviderConnectionResolver`, `ManagedEnvironmentRequiredPermissionsViewModelBuilder`, and the last `provider.connection.check` run proof, using `ProviderReasonTranslator` or `VerificationLinkBehavior` only where directly helpful rather than as mandatory primary inputs.
- [x] T034 Derive one provider guidance payload with:
  - `key`
  - `title`
  - `status`
  - `severity`
  - `reason`
  - `impact`
  - `primary_action`
  - `secondary_actions`
  - `technical_details`
- [x] T035 Keep blocker priority explicit: no connection -> disabled/unusable -> missing application -> missing delegated -> verification failed/blocked -> stale/unknown -> ready.
- [x] T036 Keep the derived guidance DB-local and request-scoped only; no new persistence.
- [x] T037 Do not introduce a new provider enum/status family, provider registry, or generic workflow engine in this slice.

## Phase 4: Provider Connections Integration

**Purpose**: Make Provider Connections read as an operator guidance destination without removing current truth.

- [x] T038 Integrate the derived guidance into Provider Connections list in a way that keeps the table scan-first and the environment filter intact.
- [x] T039 Integrate the derived guidance into Provider Connections view, and keep the edit surface aligned as action/proof continuity without forcing duplicate top guidance.
- [x] T040 Reuse existing repo-backed primary/secondary targets where appropriate:
  - `Grant admin consent`
  - `Run verification`
  - `View last check run`
  - `Open required permissions`
  - `Open provider connection`
- [x] T041 Preserve current destructive/high-impact provider actions exactly as confirmation-, authorization-, and audit-protected secondary actions.
- [x] T042 Do not let guidance visibility widen action authorization or scope.

## Phase 5: Required Permissions Integration

**Purpose**: Make Required Permissions decision-first without losing the current diagnostic depth.

- [x] T043 Add a top guidance case near the summary that explains why the current blocker matters to TenantPilot.
- [x] T044 Reuse the current capability-group and freshness truth before inventing any new provider state.
- [x] T045 Distinguish application permission blockers, delegated permission blockers, and stale/unknown verification follow-up in the top guidance layer.
- [x] T046 Keep copy payloads, feature-impact cards, and the native permission matrix as secondary detail.
- [x] T047 Keep technical details collapsed by default and avoid duplicating the blocker message in lower sections.

## Phase 6: Dashboard Target Continuity

**Purpose**: Ensure the dashboard's provider CTA lands on a destination that says the same thing clearly.

- [x] T048 Reuse the existing dashboard provider blocker mapping from `EnvironmentDashboardSummaryBuilder` and adjust destination continuity only if required.
- [x] T049 Avoid adding a fragile new query-string contract when existing route scope is sufficient.
- [x] T050 Ensure the target page shows the same blocker category and a compatible next action as the dashboard guidance.

## Phase 7: Copy, Audit, And Artifacts

**Purpose**: Align user-facing wording and UI audit coverage with the new guidance hierarchy.

- [x] T051 Update only the required copy in `apps/platform/lang/en/localization.php`.
- [x] T052 Update matching copy in `apps/platform/lang/de/localization.php`.
- [x] T053 Update `docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md`.
- [x] T054 Create or update `docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md` and align it with the final bounded route-inventory classification.
- [x] T055 Save screenshots under `specs/353-provider-connections-resolution-guidance-v1/artifacts/screenshots/`, or record the container-local Sail/Pest artifact blocker explicitly if host-visible copies cannot be persisted.
- [x] T056 Keep `repo-truth-map.md`, `contracts/provider-readiness-signal-map.md`, `docs/ui-ux-enterprise-audit/route-inventory.md`, and any conditional `design-coverage-matrix.md` / `strategic-surfaces.md` / `unresolved-pages.md` follow-through aligned with the final bounded implementation shape.

## Phase 8: Validation

**Purpose**: Prove the guidance remains bounded, scope-safe, and render-local.

- [x] T057 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/ResolutionGuidance/Spec353ProviderReadinessResolutionAdapterTest.php --compact`.
- [x] T058 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ProviderConnections/Spec353ProviderConnectionGuidanceTest.php --compact`.
- [x] T059 Run `cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec353RequiredPermissionsGuidanceTest.php --compact`.
- [x] T060 Run `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec353ProviderReadinessGuidanceSmokeTest.php --compact`.
- [x] T061 Re-run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProviderConnection --exclude-group=browser`, and document any separate browser-harness instability honestly.
- [x] T062 Re-run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=RequiredPermissions`.
- [x] T063 Re-run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec352 --exclude-group=browser`.
- [x] T064 Re-run `cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ResolutionGuidance --exclude-group=browser`.
- [x] T065 Confirm final render paths remain DB-local and do not call `GraphClientInterface` or provider HTTP during page render.
- [x] T066 Run `cd apps/platform && ./vendor/bin/sail pint --dirty`.
- [x] T067 Run `git diff --check`.
- [x] T068 Report unrelated broader-suite or fixture issues honestly if they remain outside this slice.

## Non-Goals Checklist

- [x] NT001 Do not rewrite provider verification execution or provider-connection architecture.
- [x] NT002 Do not add a new permission model, provider status persistence, or onboarding wizard flow.
- [x] NT003 Do not add auto-consent, auto-repair, or fake "make provider ready" buttons.
- [x] NT004 Do not widen Provider Connections global search, panel setup, or routing architecture.
- [x] NT005 Do not introduce live provider calls during render.
- [x] NT006 Do not add customer portal, PDF/HTML renderer, PSA, billing, or AI follow-up work.

## Required Final Report Content

When implementation later completes, report:

- changed provider-readiness behavior on Provider Connections and Required Permissions
- dominant-case selection model
- dashboard target continuity behavior
- safe action set and any disabled/fallback cases
- render-path result for no live provider calls
- UI audit artifact updates and screenshot paths
- files changed
- tests run and results
- explicit no migrations/packages/env/queues/scheduler/storage/panel/global-search change statement
- known gaps or deferred findings