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

• Lane assignment is explicit and narrow: Unit for guidance selection, Feature/Livewire for rendered integration, Browser for first-screen hierarchy and dashboard target continuity.
• New or changed tests stay in the smallest honest family, and the browser addition is explicit.
• Shared helpers, factories, seeds, and context defaults stay cheap by default.
• Planned validation commands cover the slice without pulling in unrelated lane cost.
• The changed surfaces are explicit strategic/detail surfaces, not a hidden infra-only refactor.
• 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.

• T001 Re-read spec.md, plan.md, tasks.md, repo-truth-map.md, contracts/provider-readiness-signal-map.md, and checklists/requirements.md.
• 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
• 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
• 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.
• 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.

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

• T032 Choose the narrowest implementation shape:
  • prefer one bounded provider-readiness adapter/presenter
  • avoid broadening ReviewPackOutputResolutionAdapter into a provider meta-framework
• 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.
• T034 Derive one provider guidance payload with:
  • key
  • title
  • status
  • severity
  • reason
  • impact
  • primary_action
  • secondary_actions
  • technical_details
• T035 Keep blocker priority explicit: no connection -> disabled/unusable -> missing application -> missing delegated -> verification failed/blocked -> stale/unknown -> ready.
• T036 Keep the derived guidance DB-local and request-scoped only; no new persistence.
• 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.

• T038 Integrate the derived guidance into Provider Connections list in a way that keeps the table scan-first and the environment filter intact.
• T039 Integrate the derived guidance into Provider Connections view, and keep the edit surface aligned as action/proof continuity without forcing duplicate top guidance.
• 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
• T041 Preserve current destructive/high-impact provider actions exactly as confirmation-, authorization-, and audit-protected secondary actions.
• 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.

• T043 Add a top guidance case near the summary that explains why the current blocker matters to TenantPilot.
• T044 Reuse the current capability-group and freshness truth before inventing any new provider state.
• T045 Distinguish application permission blockers, delegated permission blockers, and stale/unknown verification follow-up in the top guidance layer.
• T046 Keep copy payloads, feature-impact cards, and the native permission matrix as secondary detail.
• 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.

• T048 Reuse the existing dashboard provider blocker mapping from EnvironmentDashboardSummaryBuilder and adjust destination continuity only if required.
• T049 Avoid adding a fragile new query-string contract when existing route scope is sufficient.
• 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.

• T051 Update only the required copy in apps/platform/lang/en/localization.php.
• T052 Update matching copy in apps/platform/lang/de/localization.php.
• T053 Update docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md.
• 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.
• 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.
• 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.

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

Non-Goals Checklist

• NT001 Do not rewrite provider verification execution or provider-connection architecture.
• NT002 Do not add a new permission model, provider status persistence, or onboarding wizard flow.
• NT003 Do not add auto-consent, auto-repair, or fake "make provider ready" buttons.
• NT004 Do not widen Provider Connections global search, panel setup, or routing architecture.
• NT005 Do not introduce live provider calls during render.
• 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