Implementation Plan: Managed Tenant Onboarding Wizard v1

Branch: 069-managed-tenant-onboarding-wizard | Date: 2026-01-31 | Spec: spec.md Input: Feature specification from specs/069-managed-tenant-onboarding-wizard/spec.md

Summary

Implement a tenant-plane onboarding wizard under /admin that:

renders DB-only (no outbound HTTP during render/mount)
persists resumable onboarding sessions (non-secret payload)
triggers verification via enqueue-only OperationRun records
enforces RBAC-UX semantics (non-member 404; member missing capability 403 + disabled UI)
redirects/removes legacy onboarding entry points (notably /admin/new)

Technical Context

Language/Version: PHP 8.4.x Primary Dependencies: Laravel 12, Filament v5, Livewire v4 Storage: PostgreSQL (Sail) Testing: Pest v4 Target Platform: Web app (tenant-plane /admin, platform-plane /system) Project Type: Laravel monolith Performance Goals:

Wizard step render: DB-only
Operation starts: authorize + create/reuse OperationRun + enqueue only Constraints:
No outbound HTTP during render/mount (DB-only render).
Verification/health checks must be enqueue-only and observable via OperationRun.
Capability checks must use the canonical registry App\\Support\\Auth\\Capabilities (no raw strings).
Credential secrets must be encrypted at rest and must never be displayed back to the user. Scale/Scope: Admin workflow; correctness + auditability prioritized.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

Inventory-first: Wizard renders from stored state only (tenant fields + last run summaries), not live Graph.
Graph contract path: Any Graph verification work (when implemented) must go through the existing Graph abstraction and contract registry.
RBAC-UX: tenant-plane /admin only; non-member access is 404; member missing capability is 403; UI disabled state is not authorization.
Run observability: all verification actions create/reuse an OperationRun and enqueue work; no synchronous external calls.
Data minimization: onboarding session payload excludes secrets; failures are stable codes + sanitized messages.

Status: PASS.

Project Structure

Documentation (this feature)

specs/069-managed-tenant-onboarding-wizard/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
└── contracts/
  └── onboarding-wizard.md

Source Code (repository root)

app/
├── Filament/                  # Filament resources/pages
├── Models/                    # Eloquent models
├── Providers/Filament/         # Panel providers
├── Services/                  # OperationRun + provider gates + auth resolvers
└── Support/                   # RBAC helpers, middleware, capability registry

bootstrap/
└── providers.php              # Laravel 11+ provider registration

config/
└── graph_contracts.php

database/
└── migrations/

routes/
└── web.php

tests/
├── Feature/
└── Unit/

Structure Decision: Laravel monolith; Filament v5 discovery conventions for pages/resources.

Phase 0 — Outline & Research

Output: research.md

All NEEDS CLARIFICATION items: none remaining.

Phase 1 — Design & Contracts

Outputs:

Agent context update required after these artifacts:

Run .specify/scripts/bash/update-agent-context.sh copilot

Constitution re-check (post-design): PASS.

Phase 2 — Task Planning (produced by `/speckit.tasks`)

Planned task groups:

Data layer: tenant_onboarding_sessions migration + model.
Wizard UI: tenant-plane Filament page with 5 steps (DB-only render).
RBAC mapping (canonical registry):

Start/resume onboarding (spec: managed_tenants.create) → Capabilities::TENANT_MANAGE
Manage onboarding fields/credentials (spec: managed_tenants.manage) → Capabilities::TENANT_MANAGE
View tenant + wizard (spec: managed_tenants.view) → Capabilities::TENANT_VIEW
Enqueue provider connection checks / verification runs (spec: operations.run) → Capabilities::PROVIDER_RUN
Enqueue inventory sync (optional) → Capabilities::TENANT_INVENTORY_SYNC_RUN

Operations: enqueue-only verification action(s) backed by OperationRunService.
Legacy routes: redirect /admin/new to the existing “Choose tenant” entry point (/admin/choose-tenant).
Tests (Pest): resume/dedupe, RBAC 404/403 behavior, and run creation/dedupe.

Complexity Tracking

N/A — no constitution violations require justification.

Violation	Why Needed	Simpler Alternative Rejected Because
[e.g., 4th project]	[current need]	[why 3 projects insufficient]
[e.g., Repository pattern]	[specific problem]	[why direct DB access insufficient]

5.0 KiB Raw Blame History