ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
add1e3fe2f
TenantAtlas/specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/tasks.md

15 KiB
Raw Blame History

Tasks: Onboarding Lifecycle, Operation Checkpoints & Concurrency MVP

Input: Design documents from /specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/ Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md, contracts/onboarding-lifecycle-logical-contract.openapi.yaml

Tests: Tests are required for this feature. Each user story includes focused Pest feature, browser, or unit coverage. Operations: This feature reuses existing OperationRun flows for Verify Access and Bootstrap. Tasks below preserve the canonical OperationRun path, Ops-UX feedback contract, canonical Monitoring links, and service-owned run lifecycle transitions. Organization: Tasks are grouped by user story so each story can be implemented and validated independently after the foundational phase.

Phase 1: Setup (Shared Infrastructure)

Purpose: Add the schema and support scaffolding required for canonical lifecycle and versioned mutations.

  • T001 Create the onboarding lifecycle migration with defaults and backfill for existing draft rows in database/migrations/2026_03_14_000001_add_lifecycle_and_version_to_managed_tenant_onboarding_sessions.php
  • T002 [P] Add controlled lifecycle and checkpoint enums in app/Support/Onboarding/OnboardingLifecycleState.php and app/Support/Onboarding/OnboardingCheckpoint.php
  • T003 [P] Update onboarding session factory defaults in database/factories/TenantOnboardingSessionFactory.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Centralize workflow truth and mutation safety before any user story work begins.

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

  • T004 Implement canonical lifecycle recalculation and readiness evaluation in app/Services/Onboarding/OnboardingLifecycleService.php
  • T005 [P] Implement version-checked draft mutation orchestration in app/Services/Onboarding/OnboardingDraftMutationService.php
  • T006 [P] Extend onboarding draft casts and helpers in app/Models/TenantOnboardingSession.php and app/Support/Onboarding/OnboardingDraftStatus.php
  • T007 Refactor stage resolution to consume canonical lifecycle fields in app/Services/Onboarding/OnboardingDraftStageResolver.php
  • T008 [P] Add unit coverage for lifecycle recalculation and stage resolution in tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php and tests/Unit/Onboarding/OnboardingDraftStageResolverTest.php
  • T009 [P] Add Ops-UX regression coverage for onboarding checkpoint starts and completions in tests/Feature/OpsUx/QueuedToastCopyTest.php, tests/Feature/OperationRunServiceTest.php, and tests/Feature/Notifications/OperationRunNotificationTest.php

Checkpoint: Schema, lifecycle service, mutation service, and supporting model semantics are ready for story implementation.

Phase 3: User Story 1 - Track a trustworthy lifecycle in one wizard (Priority: P1) 🎯 MVP

Goal: Persist and render canonical lifecycle and checkpoint truth without changing the onboarding route structure.

Independent Test: Create and resume onboarding drafts across normal, blocked, active, ready, completed, and cancelled states, then confirm persisted lifecycle and checkpoint metadata drive the wizard state.

Tests for User Story 1

  • T010 [P] [US1] Expand lifecycle transition coverage in tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php
  • T011 [P] [US1] Add allow and deny lifecycle visibility assertions in tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php
  • T012 [P] [US1] Add mutation-path RBAC regression coverage for provider selection, verification, bootstrap, activation, and cancel in tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php

Implementation for User Story 1

  • T013 [US1] Route identify and provider-selection mutations through the mutation service in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T014 [US1] Persist provider-change invalidation, lifecycle reasons, and checkpoint metadata in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and app/Services/Onboarding/OnboardingLifecycleService.php
  • T015 [US1] Update wizard lifecycle labels, badges, and checkpoint summaries in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T016 [US1] Align lifecycle-aware draft resume behavior in app/Services/Onboarding/OnboardingDraftResolver.php and app/Services/Onboarding/OnboardingDraftStageResolver.php

Checkpoint: User Story 1 delivers queryable lifecycle truth and lifecycle-driven wizard progression with focused authorization coverage.

Phase 4: User Story 2 - Monitor Verify Access and Bootstrap as live checkpoints (Priority: P1)

Goal: Turn Step 3 and Step 4 into live, backend-truth checkpoint monitors while preserving Spec 139’s assist behavior.

Independent Test: Start verification and bootstrap, keep the wizard open, and confirm checkpoint state updates automatically from backend truth without losing Verify Access assist continuity.

Tests for User Story 2

  • T017 [P] [US2] Add 5s verification and bootstrap polling coverage in tests/Browser/OnboardingDraftRefreshTest.php
  • T018 [P] [US2] Add Verify Access assist compatibility coverage under active checkpoint rendering in tests/Feature/Onboarding/OnboardingVerificationAssistTest.php and tests/Browser/OnboardingDraftVerificationResumeTest.php

Implementation for User Story 2

  • T019 [US2] Add conditional 5s checkpoint polling hooks in resources/views/filament/pages/workspaces/managed-tenant-onboarding-wizard.blade.php and app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T020 [US2] Convert Verify Access to backend-truth checkpoint rendering in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and resources/views/filament/forms/components/managed-tenant-onboarding-verification-report.blade.php
  • T021 [US2] Convert Bootstrap to backend-truth per-run monitoring in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T022 [US2] Preserve canonical queued and deduped feedback plus Monitoring links for checkpoint starts in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php

Checkpoint: User Story 2 delivers live checkpoint monitoring for Verify Access and Bootstrap with Spec 139 compatibility intact.

Phase 5: User Story 3 - Prevent silent overwrite across tabs and operators (Priority: P1)

Goal: Reject stale mutations atomically and keep the operator on the wizard with clear conflict guidance.

Independent Test: Open the same draft in two tabs or sessions, save in one, then submit a stale mutation in the other and confirm the stale write is rejected with visible conflict feedback.

Tests for User Story 3

  • T023 [P] [US3] Expand multi-tab stale-mutation coverage in tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php
  • T024 [P] [US3] Add browser conflict-notification and wizard-continuity coverage in tests/Browser/OnboardingDraftRefreshTest.php

Implementation for User Story 3

  • T025 [US3] Apply expected-version checks to provider selection and inline connection edits in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and app/Services/Onboarding/OnboardingDraftMutationService.php
  • T026 [US3] Apply expected-version checks to verification, bootstrap, activation, and cancel mutations in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and app/Services/Onboarding/OnboardingDraftMutationService.php
  • T027 [US3] Enforce terminal immutability and conflict-safe refresh handling in app/Models/TenantOnboardingSession.php and app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T028 [US3] Add conflict audit coverage and messaging assertions in tests/Feature/Audit/OnboardingDraftAuditTest.php and app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php
  • T029 [US3] Add a no-takeover regression check for onboarding draft UI and services in tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php and app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php

Checkpoint: User Story 3 delivers optimistic locking across covered draft mutations with visible conflict UX and immutable terminal drafts.

Phase 6: User Story 4 - Activate only when backend truth is actually ready (Priority: P2)

Goal: Gate activation on canonical lifecycle and current checkpoint truth instead of stale visible state.

Independent Test: Bring a draft to an apparently ready state, invalidate readiness, and confirm activation refuses to complete until lifecycle truth becomes ready again.

Tests for User Story 4

  • T030 [P] [US4] Expand activation gating and terminal-state coverage in tests/Feature/Onboarding/OnboardingActivationTest.php
  • T031 [P] [US4] Add readiness-evaluation unit coverage in tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php

Implementation for User Story 4

  • T032 [US4] Rework activation readiness and override gating to use canonical lifecycle truth in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and app/Services/Onboarding/OnboardingLifecycleService.php
  • T033 [US4] Persist completed and cancelled checkpoint metadata plus terminal redirect behavior in app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php and app/Models/TenantOnboardingSession.php

Checkpoint: User Story 4 delivers backend-truth activation gating and preserves terminal record integrity.

Phase 7: Polish & Cross-Cutting Concerns

Purpose: Final validation, regression safety, and code quality across all stories.

  • T034 [P] Run focused onboarding, browser, RBAC, Ops-UX, notification, and unit tests from specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/quickstart.md
  • T035 [P] Run formatting for changed PHP files with vendor/bin/sail bin pint --dirty --format agent
  • T036 Validate the implemented flow against specs/140-onboarding-lifecycle-operation-checkpoints-concurrency-mvp/quickstart.md and update any missing regression coverage in tests/Feature/Onboarding/, tests/Feature/Rbac/, tests/Feature/OpsUx/, tests/Feature/Notifications/, tests/Browser/, and tests/Unit/Onboarding/

Dependencies & Execution Order

Phase Dependencies

  • Phase 1: Setup: No dependencies. Start immediately.
  • Phase 2: Foundational: Depends on Phase 1. Blocks all user story work.
  • Phase 3: User Story 1: Depends on Phase 2.
  • Phase 4: User Story 2: Depends on Phase 2 and can start after the foundational lifecycle service exists, but integrates cleanly after User Story 1 lifecycle persistence is in place.
  • Phase 5: User Story 3: Depends on Phase 2 and shares the mutation service introduced there.
  • Phase 6: User Story 4: Depends on Phase 2 and benefits from User Story 1 lifecycle truth plus User Story 3 mutation safety.
  • Phase 7: Polish: Depends on completion of the desired user stories.

User Story Dependencies

  • User Story 1 (P1): First MVP slice after the foundational phase. No dependency on later stories.
  • User Story 2 (P1): Depends on foundational lifecycle and checkpoint services; should be implemented after or alongside User Story 1 because it renders the lifecycle truth introduced there.
  • User Story 3 (P1): Depends on the foundational mutation service; otherwise independent of User Stories 1 and 2.
  • User Story 4 (P2): Depends on lifecycle truth from User Story 1 and version-safe mutation behavior from User Story 3.

Within Each User Story

  • Write or update the listed tests first and confirm they fail for the missing behavior.
  • Implement shared model or service changes before page rendering updates.
  • Complete the story-specific implementation before relying on it in later stories.

Suggested Execution Order

  1. Finish Phases 1 and 2.
  2. Deliver User Story 1 as the MVP.
  3. Deliver User Story 3 next if concurrency safety is the highest operational risk, or User Story 2 next if live checkpoint trust is the higher priority.
  4. Deliver the remaining P1 story.
  5. Finish User Story 4 and then run the polish phase.

Parallel Opportunities

  • Setup: T002 and T003 can run in parallel after T001 defines the schema shape.
  • Foundational: T005, T006, and T008 can run in parallel once the lifecycle service contract from T004 is settled.
  • User Story 1: T010, T011, and T012 can run in parallel.
  • User Story 2: T017 and T018 can run in parallel.
  • User Story 3: T023 and T024 can run in parallel.
  • User Story 4: T030 and T031 can run in parallel.
  • Polish: T034 and T035 can run in parallel once implementation is stable.

Parallel Example: User Story 1

# Launch lifecycle-focused tests together:
Task: "T010 Expand lifecycle transition coverage in tests/Feature/Onboarding/OnboardingDraftLifecycleTest.php"
Task: "T011 Add allow and deny lifecycle visibility assertions in tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php"
Task: "T012 Add mutation-path RBAC regression coverage in tests/Feature/Rbac/OnboardingWizardUiEnforcementTest.php"

Parallel Example: User Story 2

# Launch checkpoint-monitoring coverage together:
Task: "T017 Add verification and bootstrap polling coverage in tests/Browser/OnboardingDraftRefreshTest.php"
Task: "T018 Add Verify Access assist compatibility coverage in tests/Feature/Onboarding/OnboardingVerificationAssistTest.php and tests/Browser/OnboardingDraftVerificationResumeTest.php"

Parallel Example: User Story 3

# Launch stale-mutation coverage together:
Task: "T023 Expand multi-tab stale-mutation coverage in tests/Feature/Onboarding/OnboardingDraftMultiTabTest.php"
Task: "T024 Add browser conflict-notification and wizard-continuity coverage in tests/Browser/OnboardingDraftRefreshTest.php"

Parallel Example: User Story 4

# Launch activation readiness tests together:
Task: "T030 Expand activation gating and terminal-state coverage in tests/Feature/Onboarding/OnboardingActivationTest.php"
Task: "T031 Add readiness-evaluation unit coverage in tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php"

Implementation Strategy

MVP First

Implement Phases 1 and 2, then complete User Story 1. That yields the smallest valuable slice: canonical lifecycle truth persisted on the onboarding draft and rendered by the existing wizard without route changes.

Incremental Delivery

  • Add live checkpoint monitoring with User Story 2.
  • Add optimistic locking and visible conflict handling with User Story 3.
  • Finish backend-truth activation gating with User Story 4.

Validation Strategy

  • Keep tests close to the story they validate.
  • Reuse the focused files already present under tests/Feature/Onboarding/, tests/Feature/Rbac/, tests/Feature/OpsUx/, tests/Feature/Notifications/, tests/Browser/, and tests/Unit/Onboarding/.
  • End with the quickstart validation and focused Sail test runs before broadening to any larger regression suite.