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

Implementation Plan: Verify Access Required Permissions Assist

Branch: 139-verify-access-permissions-assist | Date: 2026-03-14 | Spec: specs/139-verify-access-permissions-assist/spec.md Input: Feature specification from specs/139-verify-access-permissions-assist/spec.md

Summary

Add a contextual Required Permissions assist to the onboarding Verify Access step without changing routing or the product role of the existing Required Permissions page. The implementation stays additive by reusing the existing verification report, next-step registry, and Required Permissions view-model builder: the wizard gets a new in-place slideover action for compact diagnostics and copy/remediation actions, permission-related verification-report next steps route into that assist first, and the deep-dive links exposed from the assist open in a new tab so the onboarding tab remains stable.

Technical Context

Language/Version: PHP 8.4 (Laravel 12)
Primary Dependencies: Filament v5 (Livewire v4), Laravel Blade, existing onboarding/verification support classes
Storage: PostgreSQL; existing JSON-backed onboarding draft state and OperationRun.context.verification_report
Testing: Pest v4 feature tests, Filament/Livewire component tests, Pest browser tests
Target Platform: Web application (Laravel Sail local environment)
Project Type: Web application

Performance Goals:

• Verify Access and the new assist render from stored DB/config-backed diagnostics only, with no provider or Graph calls during render.
• Opening or closing the assist is an in-component UI action that preserves current wizard state and feels immediate.

Constraints:

• No new routes.
• No repurposing TenantRequiredPermissions into an onboarding step.
• No duplicate permission-summary backend or onboarding-only diagnostics pipeline.
• Permission-related remediation controls in Verify Access must route through the in-place assist, and any internal or external deep-dive links that leave that recovery surface must preserve onboarding continuity by opening in a new tab.

Scale/Scope:

• One existing onboarding wizard step (Verify access) plus one existing full-page deep dive.
• Permission detail is limited to the current tenant’s configured/stored required permission dataset and existing verification report checks.
• Test scope includes targeted feature, Livewire, and browser coverage for visibility, continuity, copy feedback, and link behavior.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first / read-only render: PASS. The assist is a DB-only render surface over stored verification report + stored/config-based permission diagnostics.
• Read/write separation: PASS. No new mutation flow is introduced; rerun verification remains the existing explicit user-triggered operation with existing audit/ops behavior.
• Graph contract path: PASS. No new Graph calls or contract additions are required for this feature.
• Deterministic capabilities: PASS. Existing capability checks and tenant entitlement rules remain the source of truth; no new ad-hoc capability strings are needed.
• RBAC-UX plane separation and 404/403 semantics: PASS. The feature remains in the /admin plane; onboarding authorization and Required Permissions authorization continue unchanged.
• Workspace / tenant isolation: PASS. The assist is only available within an already authorized onboarding draft context and must reuse tenant-safe Required Permissions access semantics.
• Destructive confirmations: PASS. No destructive actions are added.
• Global search safety: PASS. No global-search behavior changes.
• Run observability and Ops-UX lifecycle: PASS. The assist creates no new OperationRun; existing verification reruns keep the current run lifecycle and feedback contract unchanged.
• Data minimization: PASS. The assist shows summary and copy payloads derived from existing permission data; no secrets are introduced.
• Badge semantics: PASS. Existing BadgeRenderer / centralized verification badge domains remain the only badge mapping source.
• UI naming: PASS. Labels remain operator-facing domain language such as View required permissions, Open full page, and Rerun verification.
• Filament Action Surface Contract: PASS with explicit exemption already documented in the spec for the in-step composite assist surface.
• UX-001: PASS with documented exemption. This is an extension of an existing wizard step, not a new CRUD form or view page.

No constitution violations are required for this feature.

Project Structure

Documentation (this feature)

specs/139-verify-access-permissions-assist/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── verification-assist.view-model.json
│   └── verification-link-behavior.md
└── tasks.md

Source Code (existing, relevant)

app/
├── Filament/
│   └── Pages/
│       ├── TenantRequiredPermissions.php
│       └── Workspaces/ManagedTenantOnboardingWizard.php
├── Filament/Support/VerificationReportViewer.php
├── Services/Intune/TenantRequiredPermissionsViewModelBuilder.php
└── Support/
    ├── Links/RequiredPermissionsLinks.php
    ├── Providers/ProviderNextStepsRegistry.php
    └── Verification/TenantPermissionCheckClusters.php
resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
tests/
├── Browser/
│   └── OnboardingDraftVerificationResumeTest.php
├── Feature/Onboarding/
│   ├── OnboardingVerificationClustersTest.php
│   ├── OnboardingVerificationTest.php
│   └── OnboardingVerificationV1_5UxTest.php
├── Feature/Rbac/
│   └── OnboardingWizardUiEnforcementTest.php
└── Unit/
  ├── RequiredPermissionsLinksTest.php
  └── TenantPermissionCheckClustersTest.php

Source Code (planned additions)

tests/
├── Feature/Onboarding/
│   └── OnboardingVerificationAssistTest.php
└── Unit/
  ├── VerificationAssistViewModelBuilderTest.php
  └── VerificationLinkBehaviorTest.php

Structure Decision: Web application (Laravel + Filament admin). Changes remain localized to the onboarding wizard page, the Verify Access Blade component, link/permission summary support code, and targeted Pest tests.

Phase 0 — Outline & Research

Key decisions (grounded in current code)

• Use an in-place Filament action on ManagedTenantOnboardingWizard to open the Required Permissions assist as a slideover.
  • Filament v5 already supports Action::make(...)->slideOver() on this page, and the wizard already uses slideovers for connection editing and technical-details inspection.
• Keep Verify Access rendering DB-only and source the assist from existing data.
  • verificationReportViewData() already exposes the current verification report for the wizard.
  • TenantRequiredPermissionsViewModelBuilder already computes the required overview, missing permission groups, freshness, and copy payloads with DB-only semantics.
• Reuse the existing Required Permissions page as the only full-page deep dive.
  • The assist should surface the same destination via RequiredPermissionsLinks::requiredPermissions() and must not introduce another page or route.
• Harden verification report remediation behavior using shared rules instead of hardcoding only one label.
  • Permission-related remediation steps in the report should open the in-place assist.
  • Internal and external diagnostic links exposed from the assist should still open in a new tab when they leave the wizard context.
• Reuse existing test suites and extend them at the nearest seams.
  • Feature / Livewire coverage belongs next to existing onboarding verification tests.
  • Browser continuity coverage belongs next to existing onboarding draft verification resume tests.

Outputs

• research.md captures the decisions, rationale, and rejected alternatives.

Phase 1 — Design & Contracts

Data model (no DB migration expected)

• No schema change is expected.
• Introduce a computed assist view model derived from:
  • the current onboarding verification report, and
  • the existing TenantRequiredPermissionsViewModelBuilder output for the same tenant.
• Define explicit action/link semantics for:
  • assist visibility,
  • copy availability and feedback,
  • full-page deep-dive behavior,
  • internal diagnostic link target behavior.

Contracts

• contracts/verification-assist.view-model.json
  • Documents the computed in-place assist payload expected by the wizard and Blade view.
• contracts/verification-link-behavior.md
  • Documents which Verify Access links must open in a new tab and how internal vs external deep-dive behavior is classified.

Outputs

• data-model.md, contracts/*, quickstart.md.

Post-design Constitution Re-check

• PASS. Phase 1 design keeps render paths DB-only, reuses existing authorization semantics, introduces no new operations or routes, and stays additive to the existing Required Permissions and onboarding surfaces.

Phase 2 — Implementation Planning (for /speckit.tasks)

Planned work items to convert into tasks.md:

1. Add Verify Access assist action plumbing on ManagedTenantOnboardingWizard.
   • Compute assist visibility from the existing verification report and stale/needs-attention context.
   • Add a slideover action with explicit secondary deep-dive behavior.
2. Add a compact assist view model + rendering layer.
   • Reuse TenantRequiredPermissionsViewModelBuilder output for summary counts, missing application/delegated groups, freshness, and copy payloads.
   • Render safe fallback states when detail is incomplete or unavailable.
3. Harden remediation behavior in the verification report Blade component.
   • Permission-related next steps route through the in-place assist.
   • Existing external and internal diagnostic links that leave the wizard from the assist continue opening in a new tab.

• Link semantics remain clear to operators, including explicit assist wording in the report and explicit new-tab wording for assist deep dives.
• Initial internal diagnostic allowlist remains limited to Required Permissions and admin Provider Connection management routes.

4. Add copy feedback behavior.
   • Show confirmation only when copy payload exists.
   • Reuse an existing clipboard/confirmation pattern instead of creating a separate UX convention.
5. Preserve authorization and continuity.

• Assist render conditions must remain authorization-safe.
• Non-members or out-of-scope actors remain 404; in-scope members missing capability remain policy-consistent denial.
• Closing the assist or opening deep dives must not alter the current wizard step.

6. Extend tests.
   • Feature/Livewire tests for assist visibility, slideover rendering, empty states, link behavior, and authorization.

• Browser tests for: deep dive opens in a new tab, the onboarding tab remains usable afterward, and the slideover does not break normal wizard controls.

7. Separate stale-state handling.

• Verification-run staleness caused by provider-connection changes stays distinct from permission-data freshness derived from stored permission diagnostics.
• Both states must render clearly and be tested independently.

Complexity Tracking

No constitution exceptions or justified complexity violations are required.