--- 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) - [X] T001 Create onboarding feature folders `app/Filament/Pages/Onboarding/`, `resources/views/filament/pages/onboarding/`, `tests/Feature/Onboarding/`, `tests/Unit/Onboarding/` - [X] T002 [P] Add a focused Pest test file scaffold for onboarding in `tests/Feature/Onboarding/OnboardingSmokeTest.php` --- ## Phase 2: Foundational (Blocking Prerequisites) - [X] T003 Create onboarding sessions migration in `database/migrations/` (new `onboarding_sessions` table per `specs/069-tenant-onboarding-wizard-v2/data-model.md`) - [X] T004 Create onboarding evidence migration in `database/migrations/` (new `onboarding_evidence` table per `specs/069-tenant-onboarding-wizard-v2/data-model.md`) - [X] T005 [P] Create `OnboardingSession` model in `app/Models/OnboardingSession.php` - [X] T006 [P] Create `OnboardingEvidence` model in `app/Models/OnboardingEvidence.php` - [X] T007 [P] Add factories for onboarding models in `database/factories/OnboardingSessionFactory.php` and `database/factories/OnboardingEvidenceFactory.php` - [X] T008 [P] Add onboarding session policy in `app/Policies/OnboardingSessionPolicy.php` (404 vs 403 semantics, capability-based) - [X] T009 [P] Add onboarding evidence policy in `app/Policies/OnboardingEvidencePolicy.php` (view-only access, capability-based) - [X] T010 Register new policies in `app/Providers/AuthServiceProvider.php` - [X] T011 [P] Create task-type enum/keys in `app/Support/Onboarding/OnboardingTaskType.php` (stable `task_type` strings) - [X] T012 [P] Create task catalog in `app/Support/Onboarding/OnboardingTaskCatalog.php` (prereqs, evidence types, operation run type/job mapping) - [X] T013 [P] Create evidence writer service in `app/Services/Onboarding/OnboardingEvidenceWriter.php` (sanitization via `App\\Support\\OpsUx\\RunFailureSanitizer`) - [X] T014 [P] Create onboarding lock service in `app/Services/Onboarding/OnboardingLockService.php` (lock acquire/renew/release + takeover) - [X] T015 [P] Add badge domain for onboarding task status in `app/Support/Badges/BadgeDomain.php` - [X] T016 [P] Add badge mapper for onboarding task status in `app/Support/Badges/Domains/OnboardingTaskStatusBadge.php` - [X] T017 Update badge catalog mapping in `app/Support/Badges/BadgeCatalog.php` for the new onboarding domain - [X] T018 [P] Add badge mapping unit tests in `tests/Unit/Badges/OnboardingBadgesTest.php` - [X] T019 [P] Add onboarding service tests for evidence sanitization in `tests/Unit/Onboarding/OnboardingEvidenceWriterTest.php` - [X] 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) - [X] T021 [P] [US1] Feature test: Owner can create/resume onboarding session in `tests/Feature/Onboarding/OnboardingSessionLifecycleTest.php` - [X] T022 [P] [US1] Feature test: non-member is denied-as-not-found (404) in `tests/Feature/Onboarding/OnboardingAuthorizationTest.php` - [X] T023 [P] [US1] Feature test: readonly can view but cannot mutate in `tests/Feature/Onboarding/OnboardingReadonlyAccessTest.php` - [X] T059 [P] [US1] Feature test: onboarding plan preview is shown before any task execution in `tests/Feature/Onboarding/OnboardingPlanPreviewTest.php` - [X] T060 [P] [US1] Feature test: duplicate onboarding/session handling navigates to resume/task board safely in `tests/Feature/Onboarding/OnboardingDuplicateHandlingTest.php` - [X] T061 [P] [US1] Feature test: consent guidance is visible in Step 4 and is safe/sanitized in `tests/Feature/Onboarding/OnboardingConsentGuidanceTest.php` - [X] T062 [P] [US1] Feature test: role-aware guidance (capability required messaging) renders for tenant members in `tests/Feature/Onboarding/OnboardingRoleGuidanceTest.php` - [X] T063 [P] [US1] Feature test: user can create a provider connection from onboarding flow (navigate + return) in `tests/Feature/Onboarding/OnboardingCreateProviderConnectionTest.php` ### Implementation - [X] T024 [US1] Add onboarding wizard page in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` (5 steps, evidence-driven status) - [X] T025 [US1] Add wizard Blade view in `resources/views/filament/pages/onboarding/tenant-onboarding-wizard.blade.php` - [X] T064 [US1] Implement onboarding plan preview in early steps (Step 1/2) using `OnboardingTaskCatalog` (tasks + prerequisites) in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` - [X] T065 [US1] Implement duplicate onboarding/session handling: always resume active session; block conflicting session creation in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` - [X] T026 [US1] Add “Resume onboarding” entry point on tenant view in `app/Filament/Resources/TenantResource/Pages/ViewTenant.php` - [X] T027 [US1] Add “Resume onboarding” entry point on provider connection pages in `app/Filament/Resources/ProviderConnectionResource/Pages/EditProviderConnection.php` - [X] T028 [US1] Implement provider connection selection/linking in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` (uses tenant-scoped `ProviderConnection`, client_secret only) - [X] 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) - [X] T066 [US1] Add “Create provider connection” path inside onboarding (navigate to ProviderConnection create and return to onboarding) in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` - [X] 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) - [X] T030 [US1] Add “Verify permissions” onboarding task start action in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` (enqueue-only, creates/reuses `OperationRun`) - [X] T031 [US1] Add onboarding verify-permissions job in `app/Jobs/Onboarding/OnboardingVerifyPermissionsJob.php` (writes `OnboardingEvidence` via `OnboardingEvidenceWriter`) - [X] T068 [US1] Add onboarding consent status job in `app/Jobs/Onboarding/OnboardingConsentStatusJob.php` (writes evidence) - [X] 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) - [X] T033 [P] [US2] Feature test: task board visible starting step 4 in `tests/Feature/Onboarding/OnboardingTaskBoardVisibilityTest.php` - [X] T034 [P] [US2] Feature test: concurrency guard blocks second run in `tests/Feature/Onboarding/OnboardingTaskConcurrencyTest.php` - [X] T035 [P] [US2] Feature test: failing task shows sanitized reason + hints in `tests/Feature/Onboarding/OnboardingFixHintsTest.php` ### Implementation - [X] T036 [US2] Add task board page in `app/Filament/Pages/Onboarding/TenantOnboardingTaskBoard.php` (lists catalog tasks + latest evidence) - [X] T037 [US2] Add task board Blade view in `resources/views/filament/pages/onboarding/tenant-onboarding-task-board.blade.php` - [X] 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}` - [X] T039 [US2] Implement prerequisite evaluation + disabled actions in `app/Support/Onboarding/OnboardingTaskCatalog.php` - [X] T040 [US2] Implement fix-hints mapping from reason codes in `app/Support/Onboarding/OnboardingFixHints.php` - [X] T041 [US2] Add onboarding connection diagnostics job in `app/Jobs/Onboarding/OnboardingConnectionDiagnosticsJob.php` (writes evidence) - [X] T042 [US2] Add onboarding initial sync job in `app/Jobs/Onboarding/OnboardingInitialSyncJob.php` (writes evidence) - [X] 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) - [X] T044 [P] [US3] Feature test: lock acquisition and read-only behavior in `tests/Feature/Onboarding/OnboardingSessionLockTest.php` - [X] T045 [P] [US3] Feature test: takeover allowed for Owner/Manager only in `tests/Feature/Onboarding/OnboardingSessionTakeoverAuthorizationTest.php` ### Implementation - [X] T046 [US3] Add lock UI banner + renew-on-interaction behavior in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` - [X] T047 [US3] Implement takeover + handoff actions in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` (capability-gated, uses `OnboardingLockService`) - [X] 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) - [X] T049 [P] [US4] Feature test: readonly can view evidence list but cannot start runs in `tests/Feature/Onboarding/OnboardingEvidenceReadonlyTest.php` ### Implementation - [X] T050 [US4] Add evidence history section to task board UI in `resources/views/filament/pages/onboarding/tenant-onboarding-task-board.blade.php` - [X] 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 - [X] T052 [P] Add v1-to-v2 credential migration action in `app/Services/Onboarding/LegacyTenantCredentialMigrator.php` (move `Tenant.app_client_secret` into `provider_credentials`) - [X] T053 Add v1 migration UI action (Owner only, requires confirmation) in `app/Filament/Pages/Onboarding/TenantOnboardingWizard.php` - [X] 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) - [X] T055 [P] Add regression test: no secrets rendered in onboarding pages in `tests/Feature/Onboarding/OnboardingNoSecretsLeakTest.php` - [X] T056 [P] Add regression test: onboarding actions use `->requiresConfirmation()` when destructive-like in `tests/Feature/Onboarding/OnboardingDestructiveActionConfirmationTest.php` - [X] 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` - [X] 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 - [X] T057 Run formatter on changed files (Pint) via `composer.json` scripts (validate using `vendor/bin/sail bin pint`) - [X] 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.