TenantAtlas/specs/240-tenant-onboarding-readiness/tasks.md

description
Task list for feature implementation

Tasks: Self-Service Tenant Onboarding & Connection Readiness

Input: Design documents from /specs/240-tenant-onboarding-readiness/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md, checklists/requirements.md

Tests: Required (Pest) for all runtime behavior changes. Keep proof in the fast-feedback lane using the onboarding, authorization, policy, and freshness suites listed in specs/240-tenant-onboarding-readiness/quickstart.md.

Test Governance Notes

• Lane assignment: fast-feedback is the narrowest sufficient proof for this slice.
• No new browser or heavy-governance family should be introduced; keep any new fixtures onboarding-local and cheap by default.
• Surface profile: standard-native-filament relief applies unless implementation widens the existing wizard/picker surface beyond the current plan.
• If implementation leaves a bounded provider-boundary hotspot or widens lane cost, record that outcome in specs/240-tenant-onboarding-readiness/plan.md and specs/240-tenant-onboarding-readiness/quickstart.md before merge.

---

Phase 1: Setup (Shared Infrastructure)

Purpose: Confirm the current onboarding baseline and pin the feature inputs before runtime edits begin.

• T001 Run the baseline fast-feedback onboarding suites listed for this feature in specs/240-tenant-onboarding-readiness/quickstart.md (specs/240-tenant-onboarding-readiness/quickstart.md, apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php, apps/platform/tests/Feature/Onboarding/OnboardingDraftPickerTest.php, apps/platform/tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php, apps/platform/tests/Unit/Policies/TenantOnboardingSessionPolicyTest.php, apps/platform/tests/Unit/TenantRequiredPermissionsFreshnessTest.php)
• T002 [P] Review the derived-only readiness contract, next-action precedence, and provider-boundary constraints before editing runtime files (specs/240-tenant-onboarding-readiness/spec.md, specs/240-tenant-onboarding-readiness/plan.md, specs/240-tenant-onboarding-readiness/research.md, specs/240-tenant-onboarding-readiness/data-model.md, specs/240-tenant-onboarding-readiness/contracts/onboarding-readiness.openapi.yaml)

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the shared derived-readiness seams that every story depends on without adding persistence, enums, or a new onboarding framework.

Critical: No user story work should start until this phase is complete.

• T003 Create a presentation-only readiness payload shell on the existing onboarding page without adding new persistence or readiness enums (apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)
• T004 [P] Thread route-bound authorization and canonical operation-link seams through that readiness payload so later story work stays inside existing workspace and tenant boundaries (apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php, apps/platform/app/Support/OperationRunLinks.php)
• T005 [P] Reuse the existing provider summary, verification assist, and permission freshness builders as the only readiness inputs so provider-specific detail stays secondary and contextual, and keep any shared-builder extension additive and behavior-preserving for non-onboarding consumers (apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php, apps/platform/app/Support/Verification/VerificationAssistViewModelBuilder.php, apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php)

Checkpoint: Foundation ready - the onboarding wizard has one derived-readiness seam and later stories can extend it without creating a second source of truth.

---

Phase 3: User Story 1 - Resume Onboarding With Trustworthy Readiness (Priority: P1)

Goal: An authorized workspace operator can open onboarding and immediately understand checkpoint progress, current readiness, freshness, and the one next action on both the landing route and the route-bound draft.

Independent Test: Seed resumable drafts in different lifecycle states, open /admin/onboarding and /admin/onboarding/{onboardingDraft}, and confirm the workflow shows progress, readiness, freshness, and one primary next action without raw operation inspection.

Tests for User Story 1

• T006 [P] [US1] Add route-bound readiness feature coverage for checkpoint progress, readiness summary, freshness cues, explicit "check has not run yet" guidance, and one primary next action in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php (apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php)
• T007 [P] [US1] Add landing-route feature coverage for compact readiness snippets on multiple drafts while preserving the existing single-draft redirect behavior in apps/platform/tests/Feature/Onboarding/OnboardingDraftPickerTest.php (apps/platform/tests/Feature/Onboarding/OnboardingDraftPickerTest.php)
• T008 [P] [US1] Extend readiness-route authorization coverage so non-members and wrong-workspace actors stay 404 while capability-denied members stay 403 in apps/platform/tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php (apps/platform/tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php)

Implementation for User Story 1

• T009 [US1] Render the derived readiness summary, checkpoint progress, freshness note, explicit "check has not run yet" guidance, and primary next-action slot on the route-bound onboarding draft view in apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)
• T010 [US1] Surface compact readiness context on the multi-draft picker without changing the landing route contract, resume flow, or view-summary affordances in apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)
• T011 [US1] Keep draft and landing progress labels aligned through the shared lifecycle and stage resolvers instead of page-local state maps in apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php and apps/platform/app/Services/Onboarding/OnboardingDraftStageResolver.php (apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php, apps/platform/app/Services/Onboarding/OnboardingDraftStageResolver.php)

Checkpoint: User Story 1 is independently functional when operators can choose or resume the correct draft from readiness context alone.

---

Phase 4: User Story 2 - Diagnose Consent And Permission Blockers (Priority: P2)

Goal: An authorized operator can tell whether onboarding is blocked by consent, permissions, or unhealthy provider connection state, and gets one concrete remediation path without introducing provider-specific top-level taxonomy.

Independent Test: Seed drafts with missing consent, revoked consent, permission gaps, and disabled connection states, then confirm each scenario renders distinct blocker language and the correct next action.

Tests for User Story 2

• T012 [P] [US2] Add blocker-matrix feature coverage for missing consent, revoked consent, disabled connection, and blocked verification scenarios in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php (apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php)
• T013 [P] [US2] Add feature coverage proving permission-gap diagnostics stay provider-owned while the top-level readiness summary stays platform-neutral in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php (apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php)
• T014 [P] [US2] Extend onboarding capability and linked-tenant entitlement policy coverage used by readiness blocker actions in apps/platform/tests/Unit/Policies/TenantOnboardingSessionPolicyTest.php (apps/platform/tests/Unit/Policies/TenantOnboardingSessionPolicyTest.php)

Implementation for User Story 2

• T015 [US2] Reuse provider connection summary state to classify consent and connection-health blockers without page-local badge or color mappings, and preserve current non-onboarding summary behavior unless an additive onboarding field is strictly required, in apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php and apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Support/Providers/TargetScope/ProviderConnectionSurfaceSummary.php, apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)
• T016 [US2] Reuse verification-assist and required-permissions builders to expose provider-owned permission diagnostics, blocked-verification guidance, and remediation links inside the onboarding workflow, keeping onboarding-specific action prioritization local and preserving existing non-onboarding outputs unless an additive field is strictly required, in apps/platform/app/Support/Verification/VerificationAssistViewModelBuilder.php, apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php, and apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Support/Verification/VerificationAssistViewModelBuilder.php, apps/platform/app/Services/Intune/TenantRequiredPermissionsViewModelBuilder.php, apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)
• T017 [US2] Enforce next-action precedence for consent, permission, and blocked-verification blockers while keeping top-level readiness wording provider-neutral in apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)

Checkpoint: User Story 2 is independently functional when blocker classification is explicit and remediation guidance is concrete without leaking Microsoft-specific terms into the top-level readiness contract.

---

Phase 5: User Story 3 - Trust Freshness And Supporting Evidence (Priority: P3)

Goal: An authorized operator can tell whether verification evidence is fresh enough to trust and can open the canonical supporting operation when deeper detail is required.

Independent Test: Seed matching, stale, and mismatched verification evidence for the same draft, then confirm readiness downgrades appropriately and only canonical Open operation links are rendered when evidence exists.

Tests for User Story 3

• T018 [P] [US3] Add feature coverage for stale evidence, selected-connection mismatch, and canonical Open operation link rendering on the route-bound draft in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php (apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php)
• T019 [P] [US3] Add landing-picker feature coverage for stale or mismatched freshness cues across multiple drafts in apps/platform/tests/Feature/Onboarding/OnboardingDraftPickerTest.php (apps/platform/tests/Feature/Onboarding/OnboardingDraftPickerTest.php)
• T020 [P] [US3] Extend freshness boundary coverage for missing and existing 30-day permission-threshold edge refresh timestamps used by readiness in apps/platform/tests/Unit/TenantRequiredPermissionsFreshnessTest.php (apps/platform/tests/Unit/TenantRequiredPermissionsFreshnessTest.php)

Implementation for User Story 3

• T021 [US3] Reuse connection-change and selected-connection-mismatch signals to downgrade readiness and surface freshness guidance on the onboarding page in apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php and apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Services/Onboarding/OnboardingLifecycleService.php, apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)
• T022 [US3] Route supporting verification and bootstrap evidence through canonical tenantless operation links only in apps/platform/app/Support/OperationRunLinks.php and apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Support/OperationRunLinks.php, apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)
• T023 [US3] Surface stale and mismatched evidence state on both the route-bound draft and the landing picker without adding persisted readiness flags in apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php (apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php)

Checkpoint: User Story 3 is independently functional when stale or mismatched evidence prevents false-ready UI and canonical evidence links remain available for legitimate detail views.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final validation, formatting, and feature-local close-out for this readiness slice.

• T024 [P] Add retained-action regression coverage proving reused consent, verification, and bootstrap start or rerun affordances still preserve shared Ops-UX, dedupe, canonical Open operation links, and audit behavior in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php (apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php)
• T025 [P] Add retained destructive-action regression coverage proving cancel or delete draft affordances remain confirmation-protected and capability-gated in apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php and apps/platform/tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php (apps/platform/tests/Feature/ManagedTenantOnboardingWizardTest.php, apps/platform/tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php)
• T026 [P] Run Laravel Pint on touched PHP files through Sail before merge (apps/platform/vendor/bin/sail)
• T027 Run the targeted fast-feedback validation suite listed in specs/240-tenant-onboarding-readiness/quickstart.md after implementation is complete (specs/240-tenant-onboarding-readiness/quickstart.md)
• T028 Record the final guardrail close-out, fast-feedback proof result, and any document-in-feature versus follow-up-spec decision for remaining provider-boundary or lane-cost notes in specs/240-tenant-onboarding-readiness/plan.md and specs/240-tenant-onboarding-readiness/quickstart.md, including the explicit defer of numeric completion score and cross-surface readiness reuse (specs/240-tenant-onboarding-readiness/plan.md, specs/240-tenant-onboarding-readiness/quickstart.md)

---

Dependencies & Execution Order

Phase Dependencies

• Phase 1 (Setup) starts immediately.
• Phase 2 (Foundational) depends on Phase 1 and blocks all user stories.
• Phase 3 (US1) depends on Phase 2 and establishes the MVP readiness surface.
• Phase 4 (US2) depends on Phase 2 and should follow US1 in practice because both stories change the same wizard and wizard test suite.
• Phase 5 (US3) depends on Phase 2 and is safest after US1 because freshness and evidence rendering extend the same readiness payload.
• Phase 6 (Polish) depends on every implemented story.

User Story Dependencies

• US1 is the MVP and the first independently shippable increment.
• US2 reuses the US1 readiness surface but remains independently testable through blocker-specific scenarios.
• US3 reuses the same readiness surface and remains independently testable through freshness and evidence scenarios.

Within Each User Story

• Write the listed Pest coverage first and ensure it fails before implementation.
• Complete service or builder changes before the final wizard rendering pass when both are required.
• Re-run the narrowest affected fast-feedback suite after each story checkpoint before moving to the next story.

---

Parallel Opportunities

Phase 1

• T001 and T002 can run in parallel if one person captures the baseline while another cross-checks the feature artifacts.

Phase 2

• T004 and T005 can run in parallel after T003 defines the readiness payload shell.

User Story 1

• T006, T007, and T008 can run in parallel.
• T009 and T011 can overlap once the shared readiness payload from Phase 2 is in place.

User Story 2

• T012, T013, and T014 can run in parallel.
• T015 and T016 can overlap before T017 finalizes next-action precedence.

User Story 3

• T018, T019, and T020 can run in parallel.
• T021 and T022 can overlap before T023 finalizes the shared stale-evidence presentation.

---

Implementation Strategy

MVP First

1. Complete Phase 1.
2. Complete Phase 2.
3. Complete Phase 3 (US1).
4. Re-run the targeted US1 fast-feedback suites and stop for review.

Incremental Delivery

1. Deliver US1 to make onboarding state understandable on landing and draft routes.
2. Add US2 to classify consent and permission blockers without broadening the provider boundary.
3. Add US3 to harden freshness and evidence trust so the readiness surface cannot go false-green.

Team Strategy

1. Finish Phase 2 together before splitting work.
2. Parallelize test authoring inside each story.
3. Sequence wizard-file merges story-by-story because all three stories converge on apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and its onboarding feature suites.