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

description
Task list for Spec 139 implementation

Tasks: Verify Access Required Permissions Assist

Input: Design documents from /specs/139-verify-access-permissions-assist/

Prerequisites: plan.md (required), spec.md (required), research.md, data-model.md, contracts/, quickstart.md

Tests: REQUIRED (Pest) for all runtime behavior changes.

RBAC (required):

• Non-member / not entitled to workspace or tenant scope → 404 (deny-as-not-found)
• Member but missing capability → policy-consistent denial
• Capabilities MUST come from App\Support\Auth\Capabilities

Badges (required):

• Reuse existing verification / permission badge domains via BadgeCatalog / BadgeRenderer

Phase 1: Setup (Shared Infrastructure)

Purpose: Confirm the touched surfaces and baseline behavior before implementation.

• T001 Validate the manual flow in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/139-verify-access-permissions-assist/quickstart.md against the current onboarding Verify Access and Required Permissions surfaces
• T002 Capture current Verify Access link-rendering and assist-touchpoint seams in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
• T003 [P] Run baseline verification coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationClustersTest.php
• T004 [P] Confirm existing Required Permissions summary/copy primitives in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/RequiredPermissionsLinksTest.php

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Shared primitives used by all user stories.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

• T005 Create the assist view-model builder in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationAssistViewModelBuilder.php using the contract from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/139-verify-access-permissions-assist/contracts/verification-assist.view-model.json
• T006 [P] Create the reusable link-classification helper in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationLinkBehavior.php using the rules from /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/139-verify-access-permissions-assist/contracts/verification-link-behavior.md
• T007 [P] Add unit coverage for assist visibility, summary shaping, and copy availability in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/VerificationAssistViewModelBuilderTest.php
• T008 [P] Add unit coverage for internal-vs-external deep-dive link classification, including Required Permissions and admin Provider Connection routes, in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Unit/VerificationLinkBehaviorTest.php
• T009 Add non-UI wizard helper methods for assist visibility and assist view-model access in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php without changing routes or onboarding draft persistence

Checkpoint: Assist view-model and link-behavior primitives are ready for story work.

---

Phase 3: User Story 1 - Recover blocked verification in place (Priority: P1) 🎯 MVP

Goal: Add a contextual in-place Required Permissions assist inside Verify Access that preserves wizard continuity.

Independent Test: Run Verify Access for a permission-blocked tenant, open the assist, review the summary and missing permissions, close it, and confirm the wizard remains on the same Verify Access state.

Tests (write first)

• T010 [P] [US1] Add feature coverage for assist visibility in blocked, needs-attention, and ready states in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php
• T011 [P] [US1] Add Livewire coverage for assist open/close continuity on the Verify Access step in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php
• T012 [P] [US1] Add rendering coverage for summary metadata and missing application/delegated permissions in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php

Implementation

• T013 [US1] Register the View required permissions slideover action in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php using the foundational helper methods from T009
• T014 [P] [US1] Create the assist slideover Blade view in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/actions/verification-required-permissions-assist.blade.php
• T015 [US1] Implement compact assist payload generation in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationAssistViewModelBuilder.php by reusing /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php and existing verification-report data
• T016 [US1] Render the assist trigger near verification result and next-step guidance in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
• T017 [US1] Render assist summary, missing-permission groups, and safe empty-state fallback in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/actions/verification-required-permissions-assist.blade.php
• T018 [US1] Preserve wizard continuity by ensuring assist open/close does not mutate draft step or verification state in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php

Checkpoint: The Verify Access step exposes a working in-place permissions assist without leaving the wizard.

---

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

Goal: Keep the full-page Required Permissions deep dive as a secondary new-tab escape hatch and harden relevant verification-report links to stop replacing the onboarding tab.

Independent Test: From Verify Access, open the assist, launch the full-page deep dive, confirm it opens in a new tab, then keep using the onboarding tab normally.

Tests (write first)

• T019 [P] [US2] Add feature coverage for internal diagnostic links and external remediation links rendering with correct new-tab behavior and explicit new-tab semantics in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationClustersTest.php
• T020 [P] [US2] Add browser coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Browser/OnboardingDraftVerificationResumeTest.php proving that opening the full-page deep dive does not replace the onboarding tab, the onboarding tab remains usable afterward, and the slideover does not break normal wizard controls
• T021 [P] [US2] Add feature coverage for full-page deep-dive availability and secondary visual placement in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php

Implementation

• T022 [US2] Implement reusable deep-dive link classification in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationLinkBehavior.php for external links, Required Permissions routes, and admin Provider Connection management routes
• T023 [US2] Harden Verify Access next-step link rendering to use the new classification helper and explicit operator-visible new-tab semantics in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
• T024 [US2] Add full-page, admin-consent, and manage-provider-connection action shaping to /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationAssistViewModelBuilder.php using /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Links/RequiredPermissionsLinks.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Providers/ProviderNextStepsRegistry.php
• T025 [US2] Render the full-page deep-dive action as clearly secondary and explicitly new-tab in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/actions/verification-required-permissions-assist.blade.php

Checkpoint: Deep-dive actions preserve onboarding continuity and remain visually secondary to the in-place assist.

---

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

Goal: Keep the assist safe and actionable when permission detail is incomplete, stale, single-type only, or not copyable.

Independent Test: Exercise incomplete detail, stale verification, no-copy payload, consent-unavailable, and single-type permission states, then verify the assist degrades safely with clear feedback.

Tests (write first)

• T026 [P] [US3] Add degraded-state rendering coverage for incomplete detail, permission-data freshness warnings, verification-run staleness after provider-connection changes, and single-type permission gaps in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php
• T027 [P] [US3] Add copy-feedback and no-copy-availability coverage in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php
• T028 [P] [US3] Add explicit authorization coverage for assist surfaces in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php, including non-member or out-of-scope 404, in-scope member missing capability denial, and positive authorized rendering

Implementation

• T029 [US3] Implement degraded-state fallback, permission-data freshness signaling, and consent-unavailable handling in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationAssistViewModelBuilder.php
• T030 [US3] Render copy actions only when payloads exist and provide explicit copied-state feedback in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/actions/verification-required-permissions-assist.blade.php
• T031 [US3] Surface verification-run staleness from provider-connection changes and rerun guidance consistently in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationAssistViewModelBuilder.php
• T032 [US3] Enforce authorization-safe assist visibility and action availability in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationAssistViewModelBuilder.php using capability-registry checks and explicit 404 vs denial semantics

Checkpoint: The assist remains understandable, authorized, and feedback-rich across degraded states.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final formatting, regression validation, and quickstart confirmation.

• T033 Run formatting on touched files with vendor/bin/sail bin pint --dirty --format agent
• T034 Run targeted Pest coverage with vendor/bin/sail artisan test --compact tests/Feature/Onboarding/OnboardingVerificationAssistTest.php tests/Feature/Onboarding/OnboardingVerificationTest.php tests/Feature/Onboarding/OnboardingVerificationClustersTest.php tests/Feature/Onboarding/OnboardingVerificationV1_5UxTest.php tests/Browser/OnboardingDraftVerificationResumeTest.php tests/Unit/VerificationAssistViewModelBuilderTest.php tests/Unit/VerificationLinkBehaviorTest.php
• T035 Validate the manual flow in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/139-verify-access-permissions-assist/quickstart.md and update the file if any step or expectation changed during implementation

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): No dependencies.
• Foundational (Phase 2): Depends on Setup; blocks all user stories.
• User Story 1 (Phase 3): Depends on Foundational completion.
• User Story 2 (Phase 4): Depends on Foundational completion and is best completed after US1 because it extends the assist surface.
• User Story 3 (Phase 5): Depends on Foundational completion and is best completed after US1 because degraded-state handling lives inside the assist.
• Polish (Phase 6): Depends on all desired user stories being complete.

User Story Dependencies

• US1 (P1): First deliverable and recommended MVP.
• US2 (P1): Builds on the assist delivered in US1.
• US3 (P2): Builds on the assist delivered in US1 and hardens edge cases.

Dependency Graph (stories)

• Foundation → US1
• US1 → US2
• US1 → US3

---

Parallel Execution Examples

US1 parallelizable tasks

• T010, T011, and T012 can run in parallel in /Users/ahmeddarrazi/Documents/projects/TenantAtlas/tests/Feature/Onboarding/OnboardingVerificationAssistTest.php as separate scenarios.
• T014 and T015 can run in parallel across /Users/ahmeddarrazi/Documents/projects/TenantAtlas/resources/views/filament/actions/verification-required-permissions-assist.blade.php and /Users/ahmeddarrazi/Documents/projects/TenantAtlas/app/Support/Verification/VerificationAssistViewModelBuilder.php.

US2 parallelizable tasks

• T019, T020, and T021 can run in parallel across feature and browser coverage.

US3 parallelizable tasks

• T026, T027, and T028 can run in parallel across degraded-state, copy-feedback, and authorization coverage.

---

Implementation Strategy

MVP First (recommended)

1. Complete Phase 1 and Phase 2.
2. Implement US1 tests first and verify they fail.
3. Implement US1 code and get the assist working in place.
4. Validate with T033–T035 before expanding scope.

Incremental Delivery

1. Add US2 to harden new-tab deep-dive behavior and keep the full page secondary.
2. Add US3 to harden degraded states, copy feedback, and authorization edges.
3. Re-run the full targeted suite and quickstart at the end.