TenantAtlas/specs/139-verify-access-permissions-assist/spec.md

Feature Specification: Verify Access Required Permissions Assist

Feature Branch: 139-verify-access-permissions-assist
Created: 2026-03-14
Status: Draft
Input: User description: "Add a contextual View required permissions assist inside the onboarding Verify Access experience, keep the existing full-page Required Permissions surface as a secondary deep-dive inside that assist, route permission-related report next steps into the assist first, preserve wizard continuity, provide clear copy feedback, avoid new routes, and keep the implementation additive to Spec 138."

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • /admin/onboarding
  • /admin/onboarding/{onboardingDraft}
  • /admin/tenants/{tenant}/required-permissions
• Data Ownership:
  • Managed tenant onboarding drafts remain workspace-scoped workflow records.
  • Verification reports, permission diagnostics, and provider connection status remain tenant-bound operational evidence already produced by existing verification flows.
  • The feature is additive only and must not introduce new tables, duplicate permission datasets, or a parallel onboarding-only permissions backend.
• RBAC:
  • Existing workspace membership and onboarding capability rules continue to govern access to the onboarding wizard.
  • Existing tenant entitlement and Required Permissions authorization continue to govern whether a user may view deep-dive permission details for the current tenant.
  • Non-members or actors outside the allowed workspace or tenant scope remain deny-as-not-found.
  • Established in-scope members missing the relevant capability continue to receive policy-consistent denial for actions they are not allowed to use.

User Scenarios & Testing (mandatory)

User Story 1 - Recover blocked verification in place (Priority: P1)

As an onboarding operator, I want a contextual Required Permissions assist directly inside Verify Access so that I can understand permission blockers and next steps without losing my place in the wizard.

Why this priority: Verification recovery is the moment where operators are most likely to lose trust if the flow forces them into separate navigation or provides incomplete guidance.

Independent Test: Run Verify Access for a tenant with permission-related blockers, open the assist from the verification result area, review the missing permissions and remediation guidance, then close it and confirm the wizard remains on the same Verify Access state.

Acceptance Scenarios:

1. Given verification is blocked for permission-related reasons, When the operator reviews the Verify Access result area, Then a prominent but secondary View required permissions assist appears near the verification result and next-step guidance.
2. Given the operator opens the assist, When the in-place panel renders, Then it shows the relevant permission summary, any missing application permissions, any missing delegated permissions, and the available remediation actions without navigating away from the wizard.
3. Given the operator closes the assist without taking action, When the panel dismisses, Then the operator returns to the same Verify Access state and the current wizard step does not change.

---

User Story 2 - Deep dive safely without breaking wizard continuity (Priority: P1)

As an operator, I want the full-page Required Permissions deep dive to remain available as a secondary action that opens safely in a new tab so that I can investigate further without replacing the onboarding tab.

Why this priority: Enterprise operators often need deeper investigation, but the onboarding tab must remain stable and resumable while they do it.

Independent Test: From a blocked Verify Access result, open the assist, launch the full-page Required Permissions experience from the assist, confirm it opens in a new tab, then continue using the onboarding wizard in the original tab.

Acceptance Scenarios:

1. Given the operator is in Verify Access with relevant permission guidance, When they choose the full-page deep dive, Then the existing Required Permissions page opens in a new tab and the onboarding tab remains on the same wizard state.
2. Given the verification report contains permission-related remediation steps, When the operator activates those controls, Then the in-place assist opens instead of replacing the onboarding wizard, and any deeper links exposed from the assist open in a new tab when they leave the wizard context.
3. Given the operator returns to the onboarding tab after opening a deep dive elsewhere, When they continue interacting with the wizard, Then normal controls and rerun verification behavior remain usable.

---

User Story 3 - Get clear recovery cues in degraded states (Priority: P2)

As an operator, I want the in-place assist to stay understandable even when diagnostic data is incomplete so that I still know what I can do next instead of seeing a broken or misleading recovery surface.

Why this priority: Permission verification often fails in partially configured environments, so degraded states must still be safe and actionable.

Independent Test: Exercise verification results with incomplete permission detail, missing consent URL, single-type permission gaps, and non-copyable payloads, then confirm the assist shows safe fallback guidance and clear copy feedback without broken controls.

Acceptance Scenarios:

1. Given verification is blocked but the permission detail payload is incomplete, When the operator opens the assist, Then the panel still renders safely with clear fallback guidance and a path to the full-page deep dive when appropriate.
2. Given there are copyable missing permissions, When the operator uses a copy action, Then the interface shows clear confirmation such as a copied state, toast, or equally clear inline acknowledgement.
3. Given there are no copyable missing permissions or the consent URL is unavailable, When the assist renders, Then unavailable actions are omitted or replaced with an appropriate alternative next step rather than a broken control.

Edge Cases

• Verification is ready and no permissions assist is needed.
• Verification is blocked but permission detail payload is incomplete.
• Permission data exists but there are no copyable missing permissions.
• Only delegated permissions are relevant.
• Only application permissions are relevant.
• Admin consent URL is unavailable.
• Provider connection exists but requires management or update.
• The full page is opened from the slideover while the wizard remains open.
• The user closes the slideover without taking action.
• The user reruns verification after reviewing the assist.
• Permission results become stale after provider connection changes.
• Links in the verification report include internal diagnostic pages other than Required Permissions.

Requirements (mandatory)

Constitution alignment (required): This feature is DB-only at render time and reuses existing verification report data, Required Permissions diagnostics, link builders, and provider next-step registries. It must not introduce new Microsoft Graph calls, new routes, new long-running operations, or a parallel permissions backend. Existing verification reruns continue to use the current verification operation path and audit behavior; the assist itself is a low-risk additive recovery surface.

Constitution alignment (OPS-UX): The assist does not create a new OperationRun. If the operator reruns verification after using the assist, that rerun continues to use the existing provider.connection.check flow and its existing 3-surface feedback contract, service-owned lifecycle transitions, and Monitoring visibility. The assist itself must not introduce new ad-hoc operation notifications.

Constitution alignment (RBAC-UX): This feature operates in the workspace-admin plane under /admin. Existing onboarding authorization continues to gate the wizard, and existing tenant entitlement plus Required Permissions authorization continue to gate deep-dive access. Non-members or actors outside workspace or tenant scope remain 404; in-scope members missing the relevant capability remain policy-consistent denials. The assist must not leak tenant existence or permission details to unauthorized users. Focused tests must cover both allowed and denied states.

Constitution alignment (BADGE-001): Any status or severity badges shown in the assist must continue using centralized verification and permission status semantics. The feature must not introduce ad-hoc badge mappings for ready, needs attention, blocked, stale, or warning states.

Constitution alignment (UI-NAMING-001): Operator-facing labels must use consistent domain language such as View required permissions, Required permissions, Open full page, Copy missing permissions, Grant admin consent, Manage provider connection, and Rerun verification. Implementation-first terms such as payload, registry, diagnostic object, or sidebar context must not become primary labels.

Constitution alignment (Filament v5 / Livewire v4): Livewire v4.0+ remains the compatibility target for this onboarding surface. No new panel is introduced and provider registration remains unchanged in bootstrap/providers.php. No new global search behavior is introduced; the Required Permissions full page keeps its existing role and remains outside onboarding step progression.

Constitution alignment (Filament Action Surfaces): The Action Surface Contract is satisfied with one explicit exemption: the Verify Access assist is a composite in-step action surface rather than a table or CRUD page, so list-table affordances do not apply. The full-page Required Permissions screen remains read-oriented and keeps its existing role.

Constitution alignment (UX-001 — Layout & Information Architecture): This feature extends an existing wizard step rather than introducing a new create, edit, or view page. The assist must appear in a predictable location near verification outcome and next-step guidance, with strong discoverability during blocked verification but lower visual weight than primary onboarding progression controls. The full-page deep dive remains visually secondary within the assist.

Functional Requirements

• FR-139-01 Contextual assist visibility: The system must show a View required permissions assist within Verify Access when verification is blocked for permissions-related reasons.
• FR-139-02 Needs-attention visibility: The system must also show the assist when verification is not fully ready and permission guidance is relevant, even if the result is not a hard block.
• FR-139-03 Ready-state suppression: The system must not show the assist when verification is fully ready and no permission guidance is relevant.
• FR-139-04 Predictable placement: The assist must appear in a predictable location near the verification result and next-step guidance inside the Verify Access experience.
• FR-139-05 Visual hierarchy: The assist must be prominent enough to discover during blocked verification but must remain visually secondary to the primary onboarding progression controls.
• FR-139-06 In-place presentation: Activating the assist must open an in-place slideover or drawer rather than navigating to a separate page.
• FR-139-07 Wizard continuity: Opening or closing the assist must not change the current wizard step or replace the current onboarding tab.
• FR-139-08 Summary rendering: The assist must show summary metadata drawn from existing verification and permission diagnostics, including the overall state and any relevant freshness or context cues needed to interpret the result.
• FR-139-09 Permission-type coverage: The assist must show missing application permissions when present and missing delegated permissions when present.
• FR-139-10 Safe empty states: The assist must render safely when detail payloads are incomplete, empty, stale, or partially missing, and must provide fallback guidance instead of a broken panel.
• FR-139-11 Copy availability: Copy actions must only appear when there is copyable missing-permission content.
• FR-139-12 Copy feedback: Every copy action must provide clear user feedback through a copied state, toast, or equally clear inline confirmation.
• FR-139-13 Full-page secondary action: The existing full-page Required Permissions experience must remain available from the assist as a secondary deep-dive action.
• FR-139-14 New-tab deep dive: The full-page deep-dive action must open in a new tab by default from the onboarding assist.
• FR-139-15 Assist-first report remediation: Permission-related remediation controls rendered from the Verify Access report must open the in-place Required Permissions assist instead of navigating away from the wizard.
• FR-139-16 External link continuity: External remediation links that leave the wizard context from the assist must continue to open in a new tab.
• FR-139-17 New-tab clarity: Any assist action or deep-dive link that opens a new tab must be visually or semantically clear enough that enterprise operators understand the behavior.
• FR-139-18 Consent fallback: If an admin consent URL is unavailable, the assist must omit the broken primary action and show the next best available guidance.
• FR-139-19 Connection-management fallback: If the provider connection exists but requires management or update, the assist must expose that remediation path using existing surfaces rather than introducing a new onboarding-only path.
• FR-139-20 Rerun continuity: After reviewing the assist, the operator must be able to rerun verification normally from the existing wizard flow.
• FR-139-21 Stale-result signaling: If provider connection changes make existing permission results stale, the assist must not present those results as current and must preserve a clear path to rerun verification.
• FR-139-22 Existing-surface reuse: The implementation must extend the existing onboarding Verify Access step, reuse the existing full-page Required Permissions page, and reuse existing builders, registries, and link helpers.
• FR-139-23 Route preservation: The feature must not introduce any new routes.
• FR-139-24 Full-page role preservation: The feature must not repurpose the full-page Required Permissions surface into an onboarding sub-step.
• FR-139-25 Additive-only scope: The feature must remain additive and low-risk, limited to a wizard assist action, compact in-place detail rendering, and hardened link behavior.
• FR-139-26 No duplicate diagnostics surface: The feature must not create a second Required Permissions page, fork permission summary logic, or introduce a separate onboarding-only permissions backend.
• FR-139-27 Authorization continuity: Assist actions and deep-dive links must render only when the underlying onboarding and tenant authorization context is valid.
• FR-139-28 Browser-level continuity coverage: Browser validation must prove that opening the deep dive does not replace the onboarding tab, the wizard remains usable afterward, and the slideover does not break normal wizard controls.

Non-Goals

• Turning the full-page Required Permissions screen into an onboarding step.
• Introducing a new route or separate deep-dive surface for onboarding-only permissions help.
• Replacing the full-page Required Permissions experience entirely.
• Changing Spec 138 concerns such as draft identity in the URL, resume disambiguation, or multi-draft landing behavior.

Assumptions

• Existing verification reporting already identifies permission-related blockers and next-step relevance well enough to drive assist visibility.
• Existing permission diagnostics already provide enough data to populate a compact in-place summary without adding a new backend source.
• Existing Required Permissions authorization and workspace-tenant isolation semantics remain correct and should be reused unchanged.
• Opening the full-page deep dive in a new tab is an acceptable enterprise pattern because it preserves wizard continuity while keeping the deeper page available.

Dependencies

• Existing onboarding Verify Access step and verification report rendering.
• Existing Required Permissions full-page experience.
• Existing permission diagnostics builders, next-step registries, and link helpers.
• Existing onboarding authorization, tenant entitlement, and browser test infrastructure.

Relationship to Spec 138

• Spec 139 is complementary to Spec 138.
• Spec 138 hardens onboarding draft identity, resume semantics, and multi-draft determinism.
• Spec 139 hardens the permission-recovery experience within the Verify Access step of that onboarding flow.
• Spec 139 must not absorb Spec 138 concerns such as draft identity in the URL, resume disambiguation, multi-draft landing behavior, or resumable lifecycle rules.

Risks and Tradeoffs

• The in-place assist is intentionally not a full replacement for the deep-dive page.
• The full page remains a separate surface because some advanced investigation still benefits from a broader, dedicated context.
• Opening the deep dive in a new tab adds one extra click context, but that tradeoff is accepted because it preserves wizard continuity and reduces accidental task loss.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Onboarding wizard: Verify Access step	/admin/onboarding, /admin/onboarding/{onboardingDraft}	View required permissions when relevant; existing Rerun verification remains primary recovery control	Not a table surface	None	None	None	Not applicable	Existing wizard Continue / Back flow remains unchanged	No new audit event required for opening or closing assist	Composite in-step assist surface; exemption from list-table affordances is intentional.
Verify Access assist slideover	In-place overlay from Verify Access	Open full page (secondary, new tab), Copy missing permissions when content exists, Grant admin consent when available, Manage provider connection when relevant	Not a table surface	None	None	Contextual fallback guidance only	Not applicable	Close returns to same wizard state	No new audit event required for read-only assistance and copy feedback	No destructive actions are introduced. New-tab behavior must be explicit in the UI.
Required Permissions full page	/admin/tenants/{tenant}/required-permissions	None added by this spec	Existing page affordances remain unchanged	None added by this spec	None added by this spec	Existing empty-state behavior remains unchanged	None added by this spec	Not applicable	No change	Product role remains unchanged; this spec only changes how onboarding links into it.

Key Entities (include if feature involves data)

• Verification Permission Assist: The in-place recovery surface shown within Verify Access when permission guidance is relevant.
• Verification Report: The existing stored verification result that determines whether permission guidance is relevant and supplies next-step context.
• Permission Diagnostics Summary: The existing permission status summary used to render counts, missing permission groups, freshness, and remediation relevance.
• Required Permissions Deep Dive: The existing full-page experience for tenant permission investigation, retained as the secondary escape hatch.

Success Criteria (mandatory)

Measurable Outcomes

• SC-139-01 Assist relevance coverage: In focused regression coverage, 100% of blocked or needs-attention verification states with permission guidance display the assist, and 100% of fully ready states without relevant permission guidance do not.
• SC-139-02 Wizard continuity: In focused Livewire and browser coverage, 100% of assist open and close flows preserve the current Verify Access step and keep the onboarding tab usable.
• SC-139-03 Safe deep-dive navigation: In focused browser coverage, 100% of relevant onboarding deep-dive links open in a new tab rather than replacing the onboarding wizard tab.
• SC-139-04 Permission detail coverage: In focused rendering coverage, the assist correctly displays application-only gaps, delegated-only gaps, mixed gaps, and safe empty or incomplete states.
• SC-139-05 Copy feedback clarity: In focused interaction coverage, 100% of available copy actions provide visible confirmation and 0 unavailable copy actions render as broken controls.
• SC-139-06 Additive architecture: The completed implementation introduces 0 new routes, 0 duplicate Required Permissions pages, and 0 onboarding-only permission backends.

Testing Requirements

Core Regression Matrix

• Verify Access assist visibility when verification is blocked for permissions-related reasons.
• Verify Access assist visibility when verification needs attention and permissions guidance is relevant.
• Verify Access assist absence when verification is fully ready and no permissions guidance is relevant.
• Slideover opens successfully from Verify Access.
• Slideover shows expected summary metadata.
• Slideover shows missing application permissions when present.
• Slideover shows missing delegated permissions when present.
• Slideover handles empty or incomplete detail states safely.
• Slideover exposes the full-page deep-dive action.
• Opening the slideover does not change the current wizard step.
• Closing the slideover returns the operator to the same Verify Access state.
• Opening the full page from the slideover does not navigate away from the wizard tab.
• Rerunning verification after closing the assist behaves normally.
• Permission-related remediation controls from the verification report open the assist in place.
• External links exposed from the assist continue to render with new-tab behavior.
• No permission-related report remediation control replaces the onboarding wizard in the same tab.
• Unauthorized users cannot see or use assist surfaces beyond existing onboarding authorization.
• Assist actions render only when the underlying context is authorized.

Browser-Level Validation

• Opening the Required Permissions deep dive from Verify Access does not replace the onboarding tab.
• The wizard remains usable after the deep dive is opened.
• The slideover does not break normal wizard controls.

Implementation Plan

Phase 1 - Navigation Safety Hardening

• Identify relevant internal diagnostic links in the verification report.
• Harden rendering so those links open in a new tab.
• Preserve existing external-link behavior.

Phase 2 - Contextual Permissions Assist

• Add the View required permissions action to the existing Verify Access step.
• Implement the in-place slideover or drawer presentation.
• Wire the assist to existing permission diagnostics data.
• Add copy, remediation, and deep-dive actions while keeping the deep dive visually secondary.

Phase 3 - Test Hardening

• Add feature, Livewire, and browser coverage for visibility, continuity, copy feedback, and navigation behavior.
• Verify no regressions to the existing Required Permissions full-page behavior.