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

Feature Specification: Spec 353 - Provider Connections Resolution Guidance v1

Feature Branch: 353-provider-connections-resolution-guidance-v1
Created: 2026-06-04
Status: Implemented (close-out audit pending)
Type: Platform productization / provider readiness guidance / operator workflow consolidation
Runtime posture: Narrow provider-readiness guidance over existing Provider Connection, Required Permissions, verification, and dashboard truth. No provider architecture rewrite, no new permission model, no onboarding rewrite, and no new persistence.
Input: User-provided Spec 353 draft + repo inspection of Provider Connections, Environment Required Permissions, Environment Dashboard provider blocker guidance, and provider verification/permission seams.

Dependencies And Historical Context

This spec is a bounded follow-up over already repo-real scope, guidance, and provider foundations:

• Spec 338 - Workspace / Environment Resource Scope Contract
• Spec 339 - Provider Connection Scope Hardening
• Spec 350 - Operator Resolution Guidance Framework v1
• Spec 351 - Review Output Resolve Actions v1
• Spec 352 - Environment Dashboard Operator Guidance Consolidation
• docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md
• docs/ui-ux-enterprise-audit/target-experience-briefs/provider-readiness.md
• docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md

Repo-truth adjustments against the user draft:

• There is no apps/platform/app/Filament/Pages/EnvironmentProviderHealth.php surface in the current repo. Provider health/readiness truth is currently spread across ProviderConnectionSurfaceSummary, ProviderConnectionHealthCheckJob, ManagedEnvironmentResource::providerConnectionState(), and EnvironmentDashboardSummaryBuilder.
• EnvironmentRequiredPermissions already exists as a repo-real page with summary, capability groups, issues, copy flows, and technical-details disclosure. Spec 353 must productize this page further instead of rebuilding it.
• ProviderConnectionResource already has list, view, and edit surfaces. The view page already exposes one primary Grant admin consent CTA and groups the rest under More.
• EnvironmentDashboardSummaryBuilder already prioritizes provider blockers by elevating required_permissions / delegated_permissions recommended actions into operatorGuidance. Spec 353 must make the target surface equally decision-first.
• docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md did not exist during prep. Close-out must create that report and align the durable UI audit registry links/classification around UI-077.
• ProviderConnectionResource is already not globally searchable. Spec 353 must preserve that state; it does not need a global-search change.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Provider readiness blockers already stop evidence refresh, review output readiness, inventory work, and onboarding continuity, but the target surfaces still force operators to translate badges, counts, and verification states into the next safe action themselves.
• Today's failure: The Environment Dashboard can now correctly say "provider readiness blocks evidence refresh", but the linked Provider Connections / Required Permissions surfaces still read as diagnostics-first. Operators can see consent, verification, and missing-permission facts without getting one clear blocker statement, one primary next action, and one safe proof path.
• User-visible improvement: Provider Connections and Required Permissions become decision-first surfaces that answer "what is wrong, why it matters, and what to do next" in five seconds while keeping raw permission rows and provider diagnostics secondary.
• Smallest enterprise-capable version: Reuse stored provider connection, permission, capability-group, verification, and last-operation truth to derive one provider guidance case with one primary action on the existing surfaces. Update dashboard-target continuity, add focused tests, and create/update the necessary UI audit artifacts.
• Explicit non-goals: No provider execution rewrite, no new provider framework, no new onboarding wizard, no new permission persistence, no consent auto-remediation, no customer portal, no PDF/HTML renderer, and no new workflow engine.
• Permanent complexity imported: One bounded provider-readiness guidance contract or presenter, focused unit/feature/browser tests, one repo-truth map, one signal inventory, and the required UI audit follow-through. No new table, model, enum family, or queue family is intended.
• Why now: Spec 352 intentionally made provider blockers outrank review-output guidance on the Environment Dashboard. Without this follow-through, the new dashboard CTA lands on destination pages that still feel diagnostic instead of operational.
• Why not local: Copy-only tweaks on one page would leave Provider Connections, Required Permissions, verification proof, and dashboard target continuity speaking different guidance dialects. A small shared derived guidance shape is the narrowest honest fix.
• Approval class: Workflow Compression.
• Red flags triggered: Strategic operator surfaces, shared interaction-family reuse, and provider-boundary vocabulary. Defense: the slice is explicitly derived-only, reuses repo-real signals, preserves existing capability/audit/OperationRun behavior, and forbids new provider architecture.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source:
  • direct user-provided Spec 353 draft
  • grouped follow-up lane: Provider onboarding/readiness UX cleanup
  • dashboard follow-up explicitly called out by Spec 352
  • provider-readiness target brief and UI-009 page report
• Completed-spec guardrail result:
  • no specs/353-* package existed before this prep
  • Specs 338, 339, 350, 351, and 352 already carry checked implementation/prep history and are treated as context only
  • no completed spec is being reopened, normalized, or converted back to preparation state
• Close alternatives deferred:
  • further Governance Inbox closure after Spec 346
  • customer-facing localization follow-through
  • commercial/artifact-lifecycle productization
  • broader provider/onboarding redesign
• Smallest viable implementation slice: existing Provider Connections list/view surfaces, existing edit-page action/proof continuity, the existing Environment Required Permissions page, and dashboard target continuity only: one dominant provider-readiness case, one primary action, secondary proof links, and technical details on demand.

Spec Scope Fields (mandatory)

• Scope: workspace-owned provider hub plus environment-owned permissions follow-through
• Primary Routes:
  • /admin/provider-connections
  • /admin/provider-connections/{record}
  • /admin/provider-connections/{record}/edit
  • /admin/workspaces/{workspace}/environments/{environment}/required-permissions
  • /admin/workspaces/{workspace}/environments/{environment}
• Data Ownership:
  • ProviderConnection remains workspace-owned and linked to ManagedEnvironment
  • permission posture remains derived from existing stored ManagedEnvironmentPermission truth through ManagedEnvironmentRequiredPermissionsViewModelBuilder
  • verification proof remains OperationRun + verification-report truth
  • any new readiness case remains derived-only; no new persistence is introduced
• RBAC:
  • existing workspace membership + environment entitlement remain authoritative
  • Provider Connection actions continue to use existing capabilities such as PROVIDER_VIEW, PROVIDER_MANAGE, and PROVIDER_RUN
  • Required Permissions page keeps deny-as-not-found workspace/environment semantics
  • no new authorization plane or hidden query authority is introduced

For canonical-view or mixed-scope follow-through:

• Default filter behavior when environment-context is active: Provider Connections continues to use explicit environment_id filtering only; Required Permissions keeps the route environment authoritative.
• Explicit entitlement checks preventing cross-tenant leakage: provider records remain record-owned and workspace-scoped; required-permissions routes remain workspace+environment scoped; dashboard deep links remain current-scope only.

UI Surface Impact (mandatory - UI-COV-001)

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact")

• Route/page/surface:
  • Provider Connections list/view
  • Provider Connections edit-page action/proof continuity without mandatory duplicate top guidance
  • Environment Required Permissions
  • Environment Dashboard provider-blocker target continuity
• Current or new page archetype:
  • Provider Connections: existing strategic provider/integration surface
  • Required Permissions: existing diagnostic/list-plus-guidance surface
• Design depth:
  • Provider Connections is already a Strategic Surface in the current audit registry
  • Required Permissions is currently a repo-verified domain surface in route-inventory.md; any promotion to Strategic Surface must be reflected in the registry during close-out
• Repo-truth level: repo-verified runtime surfaces
• Existing pattern reused:
  • Spec 350/352 resolution-guidance hierarchy
  • existing dashboard-to-detail deep-link patterns
  • existing provider verification / permission guidance links
• New pattern required: one bounded provider-readiness guidance contract or presenter; no new generic cross-domain framework
• Screenshot required: yes, under specs/353-provider-connections-resolution-guidance-v1/artifacts/screenshots/
• Page audit required:
  • update docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md
  • create or update docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md because it is currently absent in repo truth
• Customer-safe review required: no; operator/internal only
• Dangerous-action review required: yes, but only to preserve existing confirmation/authorization/audit posture on provider actions while guidance becomes more prominent
• Coverage files that must be reviewed in close-out:
  • docs/ui-ux-enterprise-audit/page-reports/ui-009-provider-connections.md
  • docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md
  • docs/ui-ux-enterprise-audit/route-inventory.md to link UI-077 and refresh UI-072/UI-077 report or screenshot references
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md only if route-inventory counts or classification change
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md only if UI-077 is intentionally promoted from its current registry classification
  • docs/ui-ux-enterprise-audit/unresolved-pages.md if browser or screenshot evidence cannot be durably stored under the Spec 353 artifact path
• No-impact rationale when applicable: N/A

Cross-Cutting / Shared Pattern Reuse (mandatory)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, next-action guidance, dashboard-to-detail continuity, verification proof links, diagnostic disclosure
• Systems touched:
  • App\Support\EnvironmentDashboard\EnvironmentDashboardSummaryBuilder
  • App\Filament\Resources\ProviderConnectionResource
  • App\Filament\Pages\EnvironmentRequiredPermissions
  • App\Services\Intune\ManagedEnvironmentRequiredPermissionsViewModelBuilder
  • App\Services\Providers\ProviderConnectionResolver
  • existing RequiredPermissionsLinks, ManagedEnvironmentLinks, and OperationRunLinks
• Existing pattern(s) to extend:
  • current operatorGuidance on the Environment Dashboard
  • existing Spec 350/352 guidance hierarchy
  • existing verification start/proof link behavior
• Shared contract / presenter / builder / renderer to reuse: existing dashboard/operator-guidance structure, ManagedEnvironmentRequiredPermissionsViewModelBuilder, ProviderConnectionResolver, and current verification/result links before adding anything broader
• Why the existing shared path is sufficient or insufficient: the repo already has the stored provider truth and one shared guidance family, but Provider Connections and Required Permissions did not yet consume that truth as one dominant provider-readiness case.
• Allowed deviation and why: one small provider-specific derived adapter is allowed because reusing the review-output adapter directly would blur provider truth and output-readiness truth.
• Consistency impact: blocker title, reason, impact, action hierarchy, and deep links must align between dashboard, provider connection, and required-permissions surfaces.
• Review focus: block a second provider-readiness dialect, fake remediation buttons, or live provider calls during render.

OperationRun UX Impact (mandatory)

• Touches OperationRun start/completion/link UX?: yes, existing provider.connection.check start and proof-link behavior only
• Shared OperationRun UX contract/layer reused:
  • existing StartVerification
  • existing ProviderOperationStartResultPresenter
  • existing OperationRunLinks
• Delegated start/completion UX behaviors: re-run verification and open last check run must reuse current queued/block/deduped/result messaging rather than inventing new start UX
• Local surface-owned behavior that remains: deciding when those existing actions are primary, secondary, or hidden based on the derived provider-readiness case
• Queued DB-notification policy: unchanged
• Terminal notification path: unchanged
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed; provider-owned signals feed a platform-owned readiness guidance layer
• Seams affected: consent status, verification status, provider capability groups, reason-code translation, operator vocabulary on shared surfaces
• Neutral platform terms preserved or introduced: provider connection, required permissions, verification, readiness, evidence refresh, operation proof
• Provider-specific semantics retained and why: provider-specific permission names and admin-consent destination remain available in details and action targets because the current provider-owned seams require them
• Why this does not deepen provider coupling accidentally: the spec forbids new Microsoft-shaped core taxonomies, persistence, or route semantics; provider-specific wording stays bounded to existing provider-owned detail.
• Follow-up path: deeper onboarding/provider health redesign stays a later follow-up candidate

UI / Surface Guardrail Impact (mandatory)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Provider Connections list	yes	Native Filament resource	provider readiness, action hierarchy, dashboard continuity	table summary, derived state	no	Existing route only
Provider Connections view	yes	Native Filament resource/detail	provider readiness, proof links, safe actions	infolist/header actions, derived state	no	Existing route only
Provider Connections edit	yes	Native Filament resource/edit	action/proof continuity, grouped safe actions	header actions, existing form context	no	Existing route only; top guidance intentionally not duplicated
Environment Required Permissions	yes	Native Filament page + custom Blade summary	permission blocker guidance, copy flows, verification links	page summary, disclosure hierarchy	no	Existing route only
Dashboard target continuity	yes	Existing dashboard -> existing destinations	guidance contract reuse	link target continuity only	no	No new dashboard scope beyond continuity

Decision-First Surface Role (mandatory)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Provider Connections view	Primary Decision Surface	Decide whether this connection is ready and what safe next action resolves the blocker	readiness state, blocker reason, impact, one primary action	capability detail, raw diagnostics, last run proof	Primary because it is the authority surface for connection-level readiness	follows provider admin workflow	removes translation from badges/columns/actions
Provider Connections edit	Secondary Configuration Context	Adjust connection metadata or review existing action/proof context after the blocker is understood	existing record fields and safe action context	last run proof, grouped provider operations, diagnostics	Secondary because the first readiness decision is already handled on list/view	follows provider admin workflow	avoids duplicating another top-level guidance layer
Environment Required Permissions	Primary Decision Surface	Decide whether missing permissions, stale evidence, or verification follow-up is the blocker	one blocker summary, one primary action, missing type split	raw permission matrix, copy payloads, technical details	Primary because dashboard often lands here first	follows permission-remediation workflow	removes need to infer next step from counts alone
Provider Connections list	Secondary Context	Decide which connection needs inspection or whether the environment has any usable connection	top-level readiness summary and row signals	detail page, diagnostics, action group	Secondary because it routes to the real connection decision	supports workspace-wide scanning	keeps list scan-first
Environment Dashboard target continuity	Secondary Context	Confirm the dashboard CTA landed on the same blocker	matching title/reason/action	deeper proof after landing	Secondary because the dashboard remains the first-start surface	preserves operator continuity	avoids target-page disorientation

Audience-Aware Disclosure (mandatory)

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Provider Connections	operator-MSP, workspace owner, support where authorized	readiness state, why blocked, impact, primary action	capability summary, consent/verification states, last error reason, last check	raw error message, detailed capability rows, operation proof	open required permissions, run verification, or open last check run depending on blocker	raw diagnostics remain secondary	guidance card states blocker once; lower sections add proof only
Environment Required Permissions	operator-MSP, workspace owner, support where authorized	missing app/delegated or stale verification blocker, why it matters, primary action	capability groups, counts, freshness, filtered highlights	raw permission matrix, copy payloads, technical details	admin consent, provider connections, or re-run verification	technical details stay collapsed by default	overview replaces the current repeated issue interpretation burden

UI/UX Surface Classification (mandatory)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Provider Connections list	Utility / Workspace Decision	Strategic integration list	inspect the blocking connection or create one	row opens view page	allowed	grouped under existing page/header patterns	existing provider actions stay grouped	/admin/provider-connections	/admin/provider-connections/{record}	workspace context + optional environment_id	Provider connection	readiness blocker and scope summary	none
Provider Connections view	Detail / Configuration Authority	Provider readiness detail	resolve the dominant blocker	existing detail page	N/A	secondary proof/actions in header group	existing destructive/high-impact actions stay confirmed and grouped	/admin/provider-connections	existing view route	workspace + record ownership	Provider connection	one derived readiness case	none
Provider Connections edit	Configuration Surface	Provider connection maintenance	adjust or review connection configuration after readiness diagnosis	existing edit page	N/A	existing grouped proof/actions remain	existing destructive/high-impact actions stay confirmed and grouped	/admin/provider-connections	existing edit route	workspace + record ownership	Provider connection	existing action/proof context only; top guidance may be deferred	intentional non-duplication of first-screen guidance
Environment Required Permissions	List / Guidance / Diagnostic	Read-first remediation page	grant consent, open provider connection, or re-run verification	same page	forbidden	secondary links in guidance/issues/details	none added	/admin/workspaces/{workspace}/environments/{environment}/required-permissions	same page	workspace + environment route	Required permissions	one blocker and one next action	inline workflow exemption remains valid

Summary

Spec 352 made provider blockers the dominant first-screen case on the Environment Dashboard. Spec 353 makes the destination surfaces trustworthy by turning existing Provider Connections and Required Permissions truth into one explicit provider-readiness guidance layer.

The feature remains narrow:

• no new provider architecture
• no new permission model
• no onboarding rewrite
• no new mutation flow
• no live provider calls during render

The product outcome is:

• one dominant provider-readiness case
• one primary next action
• secondary proof links only when repo-backed
• technical detail on demand

Problem Statement

Provider readiness is an upstream blocker for evidence refresh, review-output readiness, inventory visibility, and onboarding continuity. The repo already exposes consent status, verification status, missing-permission counts, capability-group impacts, and last-operation proof, but the affected destination surfaces still require operators to interpret those signals for themselves.

After Spec 352, the Environment Dashboard can correctly prioritize provider blockers and send the operator to a target page. That target page must now preserve the same blocker story and present one safe next action immediately, otherwise the dashboard improvement terminates in a diagnostics-first dead end.

Primary Users And Operators

• MSP operators managing multiple customer environments from the admin panel
• workspace owners or admins responsible for provider consent and verification follow-through
• internal support users with existing workspace/environment entitlement

This slice does not target customer-portal or public-facing audiences.

Goals

G1 - Add provider-readiness guidance on Provider Connections

Provider Connections list/detail must show a clear readiness case when the connection or its owning environment is blocked or needs follow-up. The edit surface may preserve action/proof continuity without duplicating first-screen guidance.

G2 - Add provider-readiness guidance on Required Permissions

Required Permissions must explain which blocker matters, why it affects TenantPilot, and what to do next before the raw permission matrix.

G3 - Reuse existing repo-backed signals

Use stored provider connection, missing-permission, capability-group, verification, and last-operation truth only.

G4 - Reuse the current guidance family only where it fits

Provider readiness may reuse Spec 350-style ResolutionCase / ResolutionAction semantics or a bounded provider presenter, but it must not force a repo-wide provider framework.

G5 - Keep provider actions safe

Only render repo-backed actions such as open required permissions, open provider connection, run verification, open last check run, or open onboarding/context destinations already supported by the repo.

G6 - Preserve domain ownership

Do not rewrite onboarding ownership, permission calculation ownership, or provider execution ownership.

Non-Goals

• rebuilding ProviderConnectionResource
• rewriting ManagedEnvironmentRequiredPermissionsViewModelBuilder
• changing provider APIs or Graph integration
• adding a new provider or provider registry layer
• adding a new OAuth or consent execution path
• adding auto-fix, auto-consent, or autonomous remediation
• adding a new dashboard framework
• changing OperationRun semantics
• adding new tables, enums, or persisted readiness states unless repo truth proves unavoidable
• turning Provider Connections into a Microsoft admin mirror

Current Repo Truth Summary

• Provider Connections already exposes consent, verification, provider capability, last check, and diagnostics on list and detail surfaces.
• The view page already has one prominent Grant admin consent action; the edit page already has View last check run and existing provider operations.
• Required Permissions already derives:
  • overall
  • counts
  • feature_impacts
  • capability_groups
  • primary_capability_group
  • freshness
• Required Permissions already renders:
  • summary counts
  • guidance copy
  • issue cards
  • copy payload modals
  • technical-details disclosure
• The Environment Dashboard already promotes required_permissions / delegated_permissions provider blockers into operatorGuidance.
• ProviderReasonTranslator and VerificationLinkBehavior remain adjacent repo seams for provider explanation/link behavior, but they are not required to be the primary runtime path for Spec 353 if a narrower adapter over stored truth is sufficient.

Provider Guidance Contract

The implementation may realize this as a Spec 350-style derived case or as a bounded provider presenter, but the product contract is:

[
    'key' => 'provider_readiness.required_permissions_missing',
    'title' => 'Provider readiness blocked',
    'status' => 'Blocked',
    'severity' => 'danger',
    'reason' => 'Required application permissions are missing.',
    'impact' => 'Evidence refresh and review output readiness may be incomplete.',
    'primary_action' => [
        'label' => 'Open required permissions',
        'url' => '...',
        'enabled' => true,
    ],
    'secondary_actions' => [
        ['label' => 'Run verification', 'url' => '...'],
        ['label' => 'Open last check run', 'url' => '...'],
    ],
    'details' => [
        'missing_application_permissions' => 15,
        'missing_delegated_permissions' => 0,
        'verification_status' => 'unknown',
        'last_error_reason_code' => 'provider_consent_missing',
    ],
]

Priority order must stay narrow and repo-backed:

1. No provider connection
2. Connection disabled or unusable
3. Missing application permissions
4. Missing delegated permissions
5. Verification failed / blocked
6. Verification not run / stale / unknown
7. Provider ready

Safe action set for v1:

• Open required permissions
• Open provider connection
• Run verification
• Open last check run
• Open environment dashboard
• Open existing onboarding destination only if current repo truth makes it the best supporting path

Unsupported for v1:

• auto-consent
• auto-repair
• "make provider ready" mutation buttons
• live provider health polling during render

Functional Requirements

• FR-353-001: Provider Connections must expose one dominant provider-readiness case on list/detail when follow-up is required. The edit surface may preserve existing proof/action continuity without duplicating the first-screen guidance layer.
• FR-353-002: Required Permissions must expose one dominant readiness case before the raw permission matrix.
• FR-353-003: Guidance must reuse stored provider connection, permission, capability-group, freshness, verification, and last-run truth only.
• FR-353-004: Guidance must distinguish at least these cases when repo-backed: no connection, disabled connection, missing application permissions, missing delegated permissions, verification blocked/failed, verification stale/unknown, ready.
• FR-353-005: Each surface must keep one visually dominant primary action. Secondary links must not compete.
• FR-353-006: Dashboard provider-blocker deep links must land on a target surface that shows the same blocker category clearly.
• FR-353-007: Raw permission rows, copy payloads, and provider diagnostics must remain secondary or collapsed by default.
• FR-353-008: Existing repo-backed actions such as Grant admin consent, Run verification, View last check run, and provider-connection navigation must be reused rather than replaced with unsupported buttons.
• FR-353-009: Existing provider/onboarding/verification behavior must remain intact; only the guidance layer changes.
• FR-353-010: Scope and authorization must remain workspace/environment safe with no cross-scope leakage.

Non-Functional Requirements

• NFR-353-001: Calm enterprise UX. The default view must read as one blocker and one next action, not a wall of permission detail.
• NFR-353-002: Provider-neutral core copy on shared surfaces. Provider-specific terms may appear in details only where current seams already require them.
• NFR-353-003: Auditability and OperationRun reuse remain unchanged. Existing verification and provider operations keep current audit and run ownership.
• NFR-353-004: Capability-first RBAC. Guidance may demote or disable actions, but server-side authorization remains authoritative.
• NFR-353-005: Render path must stay DB-local. No live Graph/provider call is allowed during guidance rendering.
• NFR-353-006: No new provider framework, no new status persistence, and no new global-search behavior.

UX Requirements

• The first visible state on the affected surfaces must answer:
  • what is blocked
  • why it matters to TenantPilot
  • what the safest next action is
• Exactly one action may be visually primary per rendered provider-readiness case.
• Raw permission rows, copy payloads, diagnostic badges, and sanitized error details must remain secondary or collapsed by default.
• Ready states must read as calm and non-alarming, with secondary proof and navigation still available when useful.
• Dashboard-to-target continuity must preserve the blocker category so the operator does not feel they landed on an unrelated admin page.

RBAC / Security Requirements

• Existing workspace membership and environment entitlement remain authoritative; deny-as-not-found behavior for out-of-scope users must not change.
• Existing provider capabilities such as PROVIDER_VIEW, PROVIDER_MANAGE, and PROVIDER_RUN continue to govern action availability.
• Guidance visibility must not widen authorization, route scope, or provider mutation reach.
• Unsupported remediation must not be rendered as executable UI.

Auditability / Observability Requirements

• Existing OperationRun ownership for provider verification and proof links remains authoritative.
• Existing provider action logging and audit semantics must remain unchanged; Spec 353 only changes decision-first presentation.
• Guidance rendering must not introduce live provider calls, background work, or untracked side effects in the request path.

Data / Truth-Source Requirements

• Provider-readiness guidance remains derived-only and request-scoped.
• Canonical inputs are existing stored truth from ProviderConnection, ManagedEnvironmentRequiredPermissionsViewModelBuilder, ProviderConnectionResolver, current link helpers, and existing OperationRun proof.
• ProviderConnectionSurfaceSummary, ProviderReasonTranslator, and VerificationLinkBehavior remain adjacent repo seams that may assist explanation or link behavior, but they are not required to be the primary runtime inputs for Spec 353.
• No new table, persisted snapshot, enum family, or provider taxonomy may be introduced unless later repo truth proves it unavoidable.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Livewire version contract: unchanged; current repo truth stays on Livewire v4.x.
• Filament panel/provider registration: unchanged; apps/platform/bootstrap/providers.php remains authoritative and is not part of this slice.
• Global search: unchanged; ProviderConnectionResource stays not globally searchable and no new searchable surface is introduced.
• Test purpose / classification:
  • Unit for deterministic provider-guidance selection
  • Feature/Livewire for Provider Connections and Required Permissions rendering/integration
  • Browser for strategic target continuity and first-screen hierarchy
• Validation lane(s): fast-feedback + confidence + browser
• Why this lane mix is the narrowest sufficient proof: the risk is decision hierarchy, continuity, and safe action truth on existing strategic surfaces rather than schema or remote execution behavior.
• Planned proving commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Unit/ResolutionGuidance/Spec353ProviderReadinessResolutionAdapterTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/ProviderConnections/Spec353ProviderConnectionGuidanceTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Filament/Spec353RequiredPermissionsGuidanceTest.php --compact
  • cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec353ProviderReadinessGuidanceSmokeTest.php --compact
• Planned regression filters:
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ProviderConnection --exclude-group=browser
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=RequiredPermissions
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=Spec352 --exclude-group=browser
  • cd apps/platform && ./vendor/bin/sail artisan test --compact --filter=ResolutionGuidance --exclude-group=browser
• Deployment/runtime impact expected: none; no migrations, env vars, queues, scheduler entries, storage changes, or filament:assets registration are planned.

Acceptance Criteria

• AC1: Provider Connections list/detail shows one dominant provider-readiness case when action is required, while edit preserves existing action/proof continuity without widening scope or faking remediation.
• AC2: Required Permissions is decision-first and explains the blocker before the raw permission matrix.
• AC3: Exactly one provider action is visually primary on the affected surfaces.
• AC4: Dashboard provider-blocker links land on a surface that shows a matching blocker clearly.
• AC5: No unsupported auto-fix, auto-consent, or fake remediation buttons are rendered.
• AC6: Guidance rendering does not call live provider APIs.
• AC7: Workspace/environment/provider scope remains correct.
• AC8: Existing provider actions, verification runs, required-permission calculation, and onboarding ownership are preserved.
• AC9: Focused unit/feature/browser tests cover missing permissions, verification follow-up, ready state, and dashboard continuity.
• AC10: UI audit artifacts and screenshots are updated under the Spec 353 package and the current UI audit registry.

Success Criteria

• An operator can land from the Environment Dashboard onto a provider-readiness target and understand the blocker plus next safe action within one screen.
• Provider Connections and Required Permissions no longer require the operator to translate badge/count truth into their own remediation decision.
• No unsupported auto-fix or auto-consent action is introduced.
• Focused validation covers blocker ranking, rendered hierarchy, and dashboard continuity without requiring broader provider rewrites.

User Scenarios & Testing (mandatory)

User Story 1 - Dashboard to provider target continuity (Priority: P1)

As an operator, when the dashboard says provider readiness blocks work, the linked page should show the same blocker and the same safe next action.

Independent Test: Seed a provider-blocked environment, open the dashboard, follow the primary provider CTA, and assert that the target surface shows a matching blocker category and one dominant action.

User Story 2 - Understand connection-level readiness (Priority: P1)

As an operator on Provider Connections, I can tell whether a specific connection is blocked by missing consent, missing permissions, stale verification, or provider failure without reading raw diagnostics first.

Independent Test: Feature/browser coverage proves that Provider Connections surfaces show one derived readiness case, one primary action, and secondary proof links only when repo-backed.

User Story 3 - Understand required-permissions impact (Priority: P1)

As an operator on Required Permissions, I can tell whether application permissions, delegated permissions, or stale verification are blocking TenantPilot and what to do next before inspecting the full matrix.

Independent Test: Feature/browser coverage proves that Required Permissions shows one blocker summary before the matrix and preserves raw permission rows as secondary detail.

User Story 4 - Calm ready state (Priority: P2)

As an operator, when provider readiness is currently satisfied, the surfaces show a calm ready state and a non-alarming next step rather than another warning stack.

Independent Test: Unit + feature/browser coverage proves the ready case yields no urgent blocker and keeps technical details secondary.

Risks

• Risk 1 - Duplicate onboarding ownership: mitigate by keeping onboarding links secondary and not rewriting onboarding state or wizard logic.
• Risk 2 - Permission details overwhelm the page: mitigate by deriving one blocker case and keeping matrix/diagnostics behind secondary disclosure.
• Risk 3 - Fake remediation: mitigate by reusing only repo-backed actions and routing unsupported cases to navigation/proof instead of mutation.
• Risk 4 - Render-time provider calls: mitigate by limiting guidance inputs to stored connection, permission, capability, freshness, and last-run truth.
• Risk 5 - Missing UI audit artifact for Required Permissions: mitigate by explicitly creating ui-077-required-permissions.md during implementation instead of silently skipping audit coverage.

Follow-Up Candidates

• accepted-risk / finding-exception resolution guidance follow-through
• broader provider/onboarding productization after this readiness slice is stable
• sellable smoke matrix after provider and governance operator flows are calmer
• customer-facing localization and copy-polish follow-through

Assumptions

• The current stored provider, permission, and verification signals are sufficient to derive one dominant readiness case without new persistence.
• Existing admin-consent, required-permissions, verification-run, and last-operation links remain the authoritative safe actions for this slice.
• Creating docs/ui-ux-enterprise-audit/page-reports/ui-077-required-permissions.md during implementation is consistent with the repo's current UI audit structure.

Open Questions

No blocking preparation questions remain.

Implementation should still confirm two narrow runtime choices during tests-first work:

• whether dashboard-target continuity can remain route-native without any new query-state hint
• whether the current repo truth prefers surfacing stale verification ahead of delegated-permission follow-up when both are present on the same environment