TenantAtlas/specs/069-tenant-onboarding-wizard-v2/tasks.md

description
Tasks for feature implementation

Tasks: Managed Tenant Onboarding Wizard UI (v2) (069)

Input: Design documents from specs/069-tenant-onboarding-wizard-v2/ Prerequisites: specs/069-tenant-onboarding-wizard-v2/plan.md (required), specs/069-tenant-onboarding-wizard-v2/spec.md (required), specs/069-tenant-onboarding-wizard-v2/research.md, specs/069-tenant-onboarding-wizard-v2/data-model.md, specs/069-tenant-onboarding-wizard-v2/contracts/, specs/069-tenant-onboarding-wizard-v2/quickstart.md

Tests: REQUIRED (Pest). This feature changes runtime behavior and introduces new models, pages, and queued operations.

Operations:

• Onboarding tasks that hit providers MUST create/reuse an OperationRun and provide a “View run” link to the canonical monitoring hub via existing helpers (see app/Support/OperationRunLinks.php).
• Concurrency rule: one active run per (tenant_id, task_type) implemented via OperationRunService::ensureRunWithIdentity().
  • tenant_id here means the internal tenant primary key (tenants.id), not the Entra tenant GUID.

RBAC:

• Non-member access MUST be deny-as-not-found (404 semantics).
• Member but missing capability MUST be forbidden (403 semantics).
• Use canonical capability registry (app/Support/Auth/Capabilities.php) and existing UiEnforcement patterns.

Badges:

• All onboarding status badges MUST use BadgeCatalog / BadgeRenderer (no ad-hoc mappings) and include mapping tests.

Phase 1: Setup (Shared Infrastructure)

• T001 Create onboarding feature folders app/Filament/Pages/Onboarding/, resources/views/filament/pages/onboarding/, tests/Feature/Onboarding/, tests/Unit/Onboarding/
• T002 [P] Add a focused Pest test file scaffold for onboarding in tests/Feature/Onboarding/OnboardingSmokeTest.php

---

Phase 2: Foundational (Blocking Prerequisites)

• T003 Create onboarding sessions migration in database/migrations/ (new onboarding_sessions table per specs/069-tenant-onboarding-wizard-v2/data-model.md)

• T004 Create onboarding evidence migration in database/migrations/ (new onboarding_evidence table per specs/069-tenant-onboarding-wizard-v2/data-model.md)

• T005 [P] Create OnboardingSession model in app/Models/OnboardingSession.php

• T006 [P] Create OnboardingEvidence model in app/Models/OnboardingEvidence.php

• T007 [P] Add factories for onboarding models in database/factories/OnboardingSessionFactory.php and database/factories/OnboardingEvidenceFactory.php

• T008 [P] Add onboarding session policy in app/Policies/OnboardingSessionPolicy.php (404 vs 403 semantics, capability-based)

• T009 [P] Add onboarding evidence policy in app/Policies/OnboardingEvidencePolicy.php (view-only access, capability-based)

• T010 Register new policies in app/Providers/AuthServiceProvider.php

• T011 [P] Create task-type enum/keys in app/Support/Onboarding/OnboardingTaskType.php (stable task_type strings)

• T012 [P] Create task catalog in app/Support/Onboarding/OnboardingTaskCatalog.php (prereqs, evidence types, operation run type/job mapping)

• T013 [P] Create evidence writer service in app/Services/Onboarding/OnboardingEvidenceWriter.php (sanitization via App\\Support\\OpsUx\\RunFailureSanitizer)

• T014 [P] Create onboarding lock service in app/Services/Onboarding/OnboardingLockService.php (lock acquire/renew/release + takeover)

• T015 [P] Add badge domain for onboarding task status in app/Support/Badges/BadgeDomain.php

• T016 [P] Add badge mapper for onboarding task status in app/Support/Badges/Domains/OnboardingTaskStatusBadge.php

• T017 Update badge catalog mapping in app/Support/Badges/BadgeCatalog.php for the new onboarding domain

• T018 [P] Add badge mapping unit tests in tests/Unit/Badges/OnboardingBadgesTest.php

• T019 [P] Add onboarding service tests for evidence sanitization in tests/Unit/Onboarding/OnboardingEvidenceWriterTest.php

• T020 [P] Add onboarding lock behavior unit tests in tests/Unit/Onboarding/OnboardingLockServiceTest.php

Checkpoint: DB schema, models, policies, badge semantics, and core services exist.

---

Phase 3: User Story 1 — Onboard a managed tenant with a provider connection (Priority: P1) 🎯 MVP

Goal: Create/resume an onboarding session, link/select a Provider Connection (client secret only), and run at least one evidence-producing verification task.

Independent Test: As an Owner, open wizard, select a provider connection, run “Verify permissions”, and see evidence-driven step/task status.

Tests (write first)

• T021 [P] [US1] Feature test: Owner can create/resume onboarding session in tests/Feature/Onboarding/OnboardingSessionLifecycleTest.php
• T022 [P] [US1] Feature test: non-member is denied-as-not-found (404) in tests/Feature/Onboarding/OnboardingAuthorizationTest.php
• T023 [P] [US1] Feature test: readonly can view but cannot mutate in tests/Feature/Onboarding/OnboardingReadonlyAccessTest.php
• T059 [P] [US1] Feature test: onboarding plan preview is shown before any task execution in tests/Feature/Onboarding/OnboardingPlanPreviewTest.php
• T060 [P] [US1] Feature test: duplicate onboarding/session handling navigates to resume/task board safely in tests/Feature/Onboarding/OnboardingDuplicateHandlingTest.php
• T061 [P] [US1] Feature test: consent guidance is visible in Step 4 and is safe/sanitized in tests/Feature/Onboarding/OnboardingConsentGuidanceTest.php
• T062 [P] [US1] Feature test: role-aware guidance (capability required messaging) renders for tenant members in tests/Feature/Onboarding/OnboardingRoleGuidanceTest.php
• T063 [P] [US1] Feature test: user can create a provider connection from onboarding flow (navigate + return) in tests/Feature/Onboarding/OnboardingCreateProviderConnectionTest.php

Implementation

• T024 [US1] Add onboarding wizard page in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php (5 steps, evidence-driven status)

• T025 [US1] Add wizard Blade view in resources/views/filament/pages/onboarding/tenant-onboarding-wizard.blade.php

• T064 [US1] Implement onboarding plan preview in early steps (Step 1/2) using OnboardingTaskCatalog (tasks + prerequisites) in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php

• T065 [US1] Implement duplicate onboarding/session handling: always resume active session; block conflicting session creation in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php

• T026 [US1] Add “Resume onboarding” entry point on tenant view in app/Filament/Resources/TenantResource/Pages/ViewTenant.php

• T027 [US1] Add “Resume onboarding” entry point on provider connection pages in app/Filament/Resources/ProviderConnectionResource/Pages/EditProviderConnection.php

• T028 [US1] Implement provider connection selection/linking in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php (uses tenant-scoped ProviderConnection, client_secret only)

• T029 [US1] Ensure secrets are never displayed by relying on existing Provider Credential patterns in app/Services/Providers/CredentialManager.php (wizard renders no secret fields)

• T066 [US1] Add “Create provider connection” path inside onboarding (navigate to ProviderConnection create and return to onboarding) in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php

• T067 [US1] Add consent guidance + optional “Check consent state” action in Step 4 in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php (sanitized UX only; no secrets)

• T030 [US1] Add “Verify permissions” onboarding task start action in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php (enqueue-only, creates/reuses OperationRun)

• T031 [US1] Add onboarding verify-permissions job in app/Jobs/Onboarding/OnboardingVerifyPermissionsJob.php (writes OnboardingEvidence via OnboardingEvidenceWriter)

• T068 [US1] Add onboarding consent status job in app/Jobs/Onboarding/OnboardingConsentStatusJob.php (writes evidence)

• T032 [US1] Feature test: starting verify-permissions creates/reuses run + evidence in tests/Feature/Onboarding/OnboardingVerifyPermissionsTaskTest.php

Checkpoint: US1 usable as MVP.

---

Phase 4: User Story 2 — Operate and recover using a task board (Priority: P2)

Goal: Provide a persistent task board (visible starting Step 4) with task statuses, history, reruns, prerequisites, and safe fix hints.

Independent Test: Run two onboarding tasks (one fail, one success), see statuses/hints, rerun and observe evidence supersedes.

Tests (write first)

• T033 [P] [US2] Feature test: task board visible starting step 4 in tests/Feature/Onboarding/OnboardingTaskBoardVisibilityTest.php
• T034 [P] [US2] Feature test: concurrency guard blocks second run in tests/Feature/Onboarding/OnboardingTaskConcurrencyTest.php
• T035 [P] [US2] Feature test: failing task shows sanitized reason + hints in tests/Feature/Onboarding/OnboardingFixHintsTest.php

Implementation

• T036 [US2] Add task board page in app/Filament/Pages/Onboarding/TenantOnboardingTaskBoard.php (lists catalog tasks + latest evidence)

• T037 [US2] Add task board Blade view in resources/views/filament/pages/onboarding/tenant-onboarding-task-board.blade.php

• T038 [US2] Implement “Start task” actions (enqueue-only) in app/Filament/Pages/Onboarding/TenantOnboardingTaskBoard.php using app/Services/OperationRunService.php identity {tenant_id, task_type}

• T039 [US2] Implement prerequisite evaluation + disabled actions in app/Support/Onboarding/OnboardingTaskCatalog.php

• T040 [US2] Implement fix-hints mapping from reason codes in app/Support/Onboarding/OnboardingFixHints.php

• T041 [US2] Add onboarding connection diagnostics job in app/Jobs/Onboarding/OnboardingConnectionDiagnosticsJob.php (writes evidence)

• T042 [US2] Add onboarding initial sync job in app/Jobs/Onboarding/OnboardingInitialSyncJob.php (writes evidence)

• T043 [US2] Ensure “View run” links use existing operation hub routing via app/Support/OperationRunLinks.php

Checkpoint: Task board supports reruns, history, prereqs, and concurrency dedupe.

---

Phase 5: User Story 3 — Collaborate safely across multiple users (Priority: P3)

Goal: Session locking + takeover/handoff with auditability; prevent conflicting edits.

Independent Test: User A locks session; User B sees read-only; Owner can takeover; actions audited.

Tests (write first)

• T044 [P] [US3] Feature test: lock acquisition and read-only behavior in tests/Feature/Onboarding/OnboardingSessionLockTest.php
• T045 [P] [US3] Feature test: takeover allowed for Owner/Manager only in tests/Feature/Onboarding/OnboardingSessionTakeoverAuthorizationTest.php

Implementation

• T046 [US3] Add lock UI banner + renew-on-interaction behavior in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php
• T047 [US3] Implement takeover + handoff actions in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php (capability-gated, uses OnboardingLockService)
• T048 [US3] Add audit log entries for takeover/handoff in app/Services/Intune/AuditLogger.php (new actions onboarding.takeover, onboarding.handoff)

Checkpoint: Collaboration is safe and auditable.

---

Phase 6: User Story 4 — Review onboarding evidence and history (Priority: P4)

Goal: Read-only users can view evidence + run metadata; no mutation.

Independent Test: As Readonly, view onboarding pages and evidence history; all actions disabled.

Tests (write first)

• T049 [P] [US4] Feature test: readonly can view evidence list but cannot start runs in tests/Feature/Onboarding/OnboardingEvidenceReadonlyTest.php

Implementation

• T050 [US4] Add evidence history section to task board UI in resources/views/filament/pages/onboarding/tenant-onboarding-task-board.blade.php
• T051 [US4] Ensure global search does not expose onboarding sessions by avoiding a Resource for sessions (no changes needed outside app/Filament/Pages/Onboarding/)

Checkpoint: Evidence/history supports audit use cases.

---

Phase 7: Polish & Cross-Cutting Concerns

• T052 [P] Add v1-to-v2 credential migration action in app/Services/Onboarding/LegacyTenantCredentialMigrator.php (move Tenant.app_client_secret into provider_credentials)

• T053 Add v1 migration UI action (Owner only, requires confirmation) in app/Filament/Pages/Onboarding/TenantOnboardingWizard.php

• T054 Update tenant creation flow to steer into onboarding in app/Filament/Resources/TenantResource/Pages/CreateTenant.php (redirect to wizard; prevent credential setup outside onboarding)

• T055 [P] Add regression test: no secrets rendered in onboarding pages in tests/Feature/Onboarding/OnboardingNoSecretsLeakTest.php

• T056 [P] Add regression test: onboarding actions use ->requiresConfirmation() when destructive-like in tests/Feature/Onboarding/OnboardingDestructiveActionConfirmationTest.php

• T069 [P] Confirm Graph contract registry coverage for new onboarding jobs; update config/graph_contracts.php if any new Graph calls are introduced (and add tests) in tests/Feature/Onboarding/OnboardingGraphContractCoverageTest.php

• T070 [P] Implement explicit v1-to-v2 “resume” semantics (define what v1 means; create v2 session when tenant has legacy credential; migrate credential) in app/Services/Onboarding/LegacyTenantCredentialMigrator.php + wizard entry points

• T057 Run formatter on changed files (Pint) via composer.json scripts (validate using vendor/bin/sail bin pint)

• T058 Run onboarding test subset via tests/Feature/Onboarding/ using vendor/bin/sail artisan test --compact

---

Dependencies & Execution Order

User Story Dependencies (graph)

• Setup → Foundational → US1 → US2 → US3 → US4 → Polish

Notes:

• US2 depends on the task catalog + evidence store (Foundational) and the wizard/session surface (US1).
• US3 depends on session existence + lock fields (Foundational + US1).
• US4 depends on evidence storage + task board UI (Foundational + US2).

Parallel opportunities (examples)

Foundational (safe parallel work):

• T005/T006 models, T011/T012 catalog, T015/T016 badges, T019/T020 unit tests.

US1:

• T021–T023 tests can run in parallel.
• T024–T025 page + view can run in parallel.

US2:

• T033–T035 tests can run in parallel.
• T041 and T042 jobs can run in parallel.

---

Implementation Strategy

MVP scope (recommended)

• Complete Phase 1 + Phase 2 + Phase 3 (US1). Stop and validate using the independent test in the spec.

Incremental delivery

• Add US2 for operational recovery (task board) next.
• Add US3 (collaboration lock) once core flow is stable.
• Add US4 (audit/read-only evidence) last.