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

Research — Spec 139 (Verify Access Required Permissions Assist)

Decisions

1) Use a page action slideover on the existing onboarding wizard

• Decision: Implement the contextual assist as a Filament action on ManagedTenantOnboardingWizard that opens a slideover from the existing Verify Access step.
• Rationale:
  • The page already uses Filament v5 Action::make(...)->slideOver() successfully for other in-place workflows.
  • This preserves wizard continuity, satisfies the no-new-route requirement, and keeps the assist visually subordinate to the main step progression.
• Alternatives considered:
  • Full-page navigation only: rejected because it breaks onboarding continuity and duplicates the exact problem this spec is meant to solve.
  • A separate onboarding-only page or route: rejected because the spec explicitly forbids new routes and parallel surfaces.

2) Reuse the existing Required Permissions builder as the source of compact diagnostics

• Decision: Reuse TenantRequiredPermissionsViewModelBuilder as the canonical source for summary counts, overall status, freshness, missing application permissions, missing delegated permissions, and copy payloads.
• Rationale:
  • The builder already provides DB-only permission diagnostics and copy payload semantics.
  • Reusing it avoids forking permission summary logic and keeps the onboarding assist consistent with the full-page deep dive.
• Alternatives considered:
  • Recomputing a second onboarding-specific summary from verification-report evidence alone: rejected because it would drift from the Required Permissions page and violate the additive-only intent.

3) Classify deep-dive links by behavior, not only by absolute URL scheme

• Decision: Harden Verify Access next-step link rendering with a shared internal-vs-deep-dive classification rule so relevant internal diagnostic links also open in a new tab.
• Rationale:
  • The current Blade template opens only absolute external URLs in a new tab.
  • Spec 139 requires internal diagnostic links from the verification report to stop replacing the onboarding tab, including pages other than Required Permissions.
• Alternatives considered:
  • Hardcoding Open required permissions as the only new-tab internal link: rejected because the spec explicitly calls out other internal diagnostic links.
  • Opening every internal /admin/* link in a new tab: rejected because not every internal link is a deep-dive escape hatch, and broad behavior changes would be too risky.

4) Keep the full-page Required Permissions page as the only deep-dive surface

• Decision: The assist will expose Open full page as a clearly secondary action that points to the existing TenantRequiredPermissions page via RequiredPermissionsLinks::requiredPermissions().
• Rationale:
  • This preserves the current product role of the page and avoids route sprawl.
  • The deep dive remains available for advanced investigation while the onboarding tab stays on task.
• Alternatives considered:
  • Replacing the full page with the slideover: rejected because the spec accepts that some advanced investigation still belongs on the full page.

5) Copy feedback should follow an explicit visible confirmation pattern

• Decision: Copy actions will only render when the relevant copy payload exists, and each copy action will provide explicit confirmation through a visible copied state, toast, or equivalent inline acknowledgement.
• Rationale:
  • The spec requires clear feedback and safe handling when no copyable data exists.
  • Reusing an existing clipboard feedback pattern is lower risk than inventing a new one.
• Alternatives considered:
  • Silent clipboard copy: rejected because it gives poor operator feedback.
  • Always-rendered disabled copy buttons for empty payloads: rejected because omitted or replaced actions are clearer in degraded states.

6) Extend existing onboarding verification tests instead of creating a separate test pyramid

• Decision: Add focused coverage in the existing onboarding verification feature, Livewire, and browser test areas.
• Rationale:
  • The current repository already has strong seams around verification report rendering, slideover actions, stale verification continuity, and clustered checks.
  • Extending those tests gives the best regression value with minimal new scaffolding.
• Alternatives considered:
  • Creating a new isolated end-to-end-only suite for the assist: rejected because visibility rules and degraded-state rendering are faster and more deterministically covered in feature/Livewire tests.

Resolved Clarifications

How should the assist determine whether it is relevant?

• Decision: Relevance is driven by the stored verification report plus the existing permission diagnostics summary for the selected tenant.
• Rationale:
  • The verification report already communicates permission-related blockers and next steps.
  • The Required Permissions builder already exposes the underlying permission state needed for compact rendering.

What should happen when permission detail is incomplete or stale?

• Decision: The assist still renders but degrades to safe fallback messaging, surfaces freshness/needs-attention context when available, and preserves rerun/deep-dive options instead of showing broken controls.
• Rationale:
  • This matches the spec’s degraded-state requirements and keeps the recovery surface trustworthy.

Does this feature need new backend persistence?

• Decision: No. The feature is computed entirely from existing onboarding draft state, the stored verification report, and existing permission diagnostics services.
• Rationale:
  • This keeps the implementation additive and low risk.