TenantAtlas/specs/138-managed-tenant-onboarding-draft-identity/spec.md

Feature Specification: Managed Tenant Onboarding Draft Identity & Resume Semantics

Feature Branch: 138-managed-tenant-onboarding-draft-identity
Created: 2026-03-13
Status: Proposed
Input: User description: "Spec 138 — Managed Tenant Onboarding Draft Identity & Resume Semantics"

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • /admin/onboarding
  • /admin/onboarding/{onboardingDraft}
• Data Ownership:
  • managed_tenant_onboarding_sessions remain workspace-scoped onboarding draft workflow records represented in the UI as onboarding drafts
  • The draft model uses the constitution-approved workflow exception: workspace_id is always required and tenant_id remains nullable until identification, then acts as an authorization and continuity reference rather than redefining the draft as a generic tenant-owned record
  • Confirmed onboarding state remains DB-backed and tenant-aware, while transient unsaved step input remains Livewire-only
  • Provider connection, verification, bootstrap, and activation references remain existing operational records linked from the draft rather than copied into parallel shadow objects
• RBAC:
  • Workspace membership remains mandatory for all onboarding draft discovery and access
  • Users with onboarding management capability may view and resume resumable drafts in their current workspace
  • Non-members, cross-workspace requests, and actors lacking tenant entitlement for an identified draft remain deny-as-not-found
  • Established in-scope workspace members who lack onboarding capability receive policy-consistent 403 denial on execution or page access
  • Destructive lifecycle actions such as cancelling a draft remain capability-gated, confirmed, and auditable

User Scenarios & Testing (mandatory)

User Story 1 - Deterministic draft identity and routing (Priority: P1)

As an authorized workspace operator, I want every onboarding draft to have an explicit identity and canonical URL so that refresh and revisit always reopen the same work item instead of relying on heuristics.

Why this priority: Without explicit draft identity, the onboarding wizard remains untrustworthy on refresh, revisit, and bookmarks.

Independent Test: Visit /admin/onboarding, create or resume a draft, confirm that the browser moves to /admin/onboarding/{draft}, then reload and verify that the same draft and confirmed state are restored.

Acceptance Scenarios:

1. Given no resumable drafts exist in the current workspace, When the user visits /admin/onboarding, Then the landing experience shows a clean start state for a new onboarding draft.
2. Given exactly one resumable draft exists in the current workspace, When the user visits /admin/onboarding, Then the request redirects to /admin/onboarding/{draft} for that draft.
3. Given a concrete draft route is visited, When the draft is valid and accessible, Then the wizard loads confirmed state from the database and remains anchored to that draft identity across hard refresh.

---

User Story 2 - Clear resume and multi-draft behavior (Priority: P1)

As an operator, I want the system to make ambiguity explicit when multiple drafts exist so that I never lose trust because the wizard silently chooses the wrong draft or falls back to blank Step 1.

Why this priority: Enterprise operators need a reliable mental model of which draft they are resuming and why.

Independent Test: Seed multiple open drafts in one workspace, visit /admin/onboarding, confirm that a draft picker appears, then choose a draft and verify the wizard shows clear resume context and the correct derived step.

Acceptance Scenarios:

1. Given multiple resumable drafts exist, When the user lands on /admin/onboarding, Then the UI shows a draft picker and does not silently choose one.
2. Given a user resumes a draft from the picker, When the wizard opens, Then it displays a resume banner with tenant identity, current stage, and attribution metadata.
3. Given an existing resumable draft already targets the same managed tenant, When the user tries to create another one, Then the UI warns and offers resume-first behavior before creating a duplicate.

---

User Story 3 - Enterprise lifecycle, visibility, and safety (Priority: P2)

As a workspace onboarding manager, I want draft lifecycle state, attribution, cancellation, and non-resumable handling to be explicit so that teams can share continuity without unsafe reopening of completed or cancelled work.

Why this priority: Shared operational continuity requires visible attribution and clear resumable versus historical state.

Independent Test: Resume a draft started by another authorized operator, cancel a draft, complete a draft, and verify the list, direct URL behavior, and authorization rules all behave deterministically.

Acceptance Scenarios:

1. Given a resumable draft was started by another authorized workspace operator, When a second authorized operator resumes it, Then the draft remains accessible and the UI shows started-by and last-updated-by attribution.
2. Given a draft is cancelled or completed, When a user visits its direct route, Then the system does not reopen the editable wizard and instead fails closed into non-editable handling.
3. Given a user lacks workspace membership or tenant entitlement for an identified draft, When they attempt to load a draft route, Then the system responds with policy-consistent deny-as-not-found behavior.
4. Given a user is an established in-scope workspace member but lacks onboarding capability, When they attempt to load or mutate a draft, Then the system responds with policy-consistent 403 denial.

---

User Story 4 - Verified refresh and resume behavior under real browser conditions (Priority: P2)

As a product owner, I want browser-level regression coverage for refresh, multi-tab, and stale verification behavior so that future changes cannot reintroduce progress-loss confusion.

Why this priority: The defect only becomes trustworthy when hard refresh is validated in a real browser and multi-tab behavior is deterministic.

Independent Test: Run browser tests that create or resume a draft on /admin/onboarding/{draft}, reload the page, revisit the URL, and assert that confirmed state, verification warnings, and non-rehydrated secrets behave correctly.

Acceptance Scenarios:

1. Given the user hard-refreshes a draft URL after confirming Step 1 or Step 2, When the page reloads, Then confirmed state is restored and the wizard resumes on the correct derived step.
2. Given the same draft is open in two tabs, When later confirmed writes occur, Then state remains deterministic and business invariants stay protected.
3. Given verification becomes stale because the selected provider connection changed, When the draft is revisited, Then the stale verification warning remains visible and activation guards still apply.

Edge Cases

• Zero open drafts in a workspace.
• Exactly one open draft in a workspace.
• Multiple open drafts in a workspace.
• Multiple drafts for the same target tenant.
• Draft created by one operator and resumed by another authorized operator.
• Completed draft direct URL access.
• Cancelled draft direct URL access.
• Stale verification after provider connection change.
• Same draft open in multiple tabs.
• Refresh during verification or bootstrap.
• Workspace switch while a concrete draft URL is open.
• Unauthorized or cross-workspace draft access.
• Old bookmarks targeting a draft that has since completed.

Requirements (mandatory)

Constitution alignment (required): This feature hardens an existing onboarding workflow without changing Graph contract ownership. It formalizes onboarding drafts as first-class workspace-scoped workflow records, uses the constitution-approved managed_tenant_onboarding_sessions exception for nullable tenant_id continuity, keeps confirmed progress DB-backed, preserves read/write separation by only persisting at explicit step-confirmation boundaries, and requires audit coverage plus focused tests for all lifecycle-changing actions.

Constitution alignment (RBAC-UX): Workspace membership and onboarding capability remain the source of truth. Non-members, cross-workspace requests, and actors lacking tenant entitlement for an identified draft remain deny-as-not-found. Established in-scope members who lack onboarding capability must receive 403. Authorized workspace operators may view and resume workspace drafts for operational continuity, while destructive lifecycle actions such as cancel must remain server-authorized, confirmation-gated, and audited.

Constitution alignment (OPS-UX): Verification and bootstrap flows that already create or reuse OperationRun records keep the existing Ops-UX contract. This spec changes only resume semantics and draft anchoring; it does not introduce inline remote work during page render or new ad-hoc notification patterns.

Constitution alignment (UI-NAMING-001): Operator-facing copy must consistently use terms such as Onboarding draft, Resume onboarding draft, Start new onboarding, Current stage, Started by, and Last updated by. Internal implementation terms like session, payload, or heuristic must not become primary operator-facing labels.

Constitution alignment (Filament v5): Livewire v4.0+ remains the compatibility target. No new panel is introduced, so provider registration remains unchanged in bootstrap/providers.php. Any destructive lifecycle actions added to Filament surfaces must execute through confirmed actions with server-side authorization. No new global search behavior is required by this spec.

Functional Requirements

• FR-138-01 Canonical draft identity: The system must treat each managed tenant onboarding draft as a first-class persisted object with an explicit identity.
• FR-138-02 Canonical landing route: The system must support /admin/onboarding as the landing route for starting, resuming, or selecting onboarding drafts.
• FR-138-03 Canonical draft route: The system must support /admin/onboarding/{onboardingDraft} as the canonical route for operating on one explicit onboarding draft.
• FR-138-04 Landing zero-draft behavior: When no resumable drafts exist in the current workspace, /admin/onboarding must show a fresh onboarding start state.
• FR-138-05 Landing single-draft behavior: When exactly one resumable draft exists in the current workspace, /admin/onboarding must redirect to that concrete draft route.
• FR-138-06 Landing multi-draft behavior: When multiple resumable drafts exist, /admin/onboarding must show a draft-selection UI and must not silently pick one or silently restart a blank wizard.
• FR-138-07 Fail-closed draft access: Draft route access must fail closed: non-existent drafts, cross-workspace requests, and actors lacking scope entitlement must return 404, while established in-scope members lacking onboarding capability must return policy-consistent 403.
• FR-138-08 Explicit resumable lifecycle: Drafts must distinguish resumable versus non-resumable states, with at least draft, completed, and cancelled lifecycle semantics.
• FR-138-09 Non-resumable drafts stay non-editable: Completed and cancelled drafts must not reopen the editable wizard and must not appear in the open draft picker.
• FR-138-10 Data-derived step resume: Resume step selection must be derived from persisted confirmed data and workflow state, not solely from current_step.
• FR-138-11 current_step remains diagnostic: The draft may continue storing current_step, but it must remain diagnostic or audit metadata rather than the sole source of resume truth.
• FR-138-12 Confirmed state durability: Once a step is confirmed and persisted, refresh and revisit must restore that confirmed state from the database.
• FR-138-13 Transient unsaved edits remain transient: Unsaved edits on the current step may be lost on hard refresh and must not be represented to operators as durable.
• FR-138-14 Sensitive fields never rehydrate: Secrets, raw credential material, and temporary authorization material must never be restored into UI fields from draft or session state.
• FR-138-15 Provider references may restore: Non-secret references such as selected provider connection, verification references, and bootstrap references may be restored from confirmed draft state.
• FR-138-16 Orientation banner: The wizard must show explicit resume orientation for concrete drafts, including tenant identity, current stage, and attribution metadata.
• FR-138-17 Duplicate warning: When a resumable draft already exists for the same target tenant, the UI must warn and prefer resume-first behavior instead of blind duplicate creation.
• FR-138-18 Explicit new draft intent: Starting a new draft while another resumable draft exists must be an explicit user action.
• FR-138-19 Post-step-1 canonicalization: Once Step 1 identifies and confirms the target tenant, the flow must create or attach the correct draft and redirect the browser to the canonical draft URL.
• FR-138-20 Draft list metadata: The draft picker must show tenant name, tenant identifier, environment if available, current stage, status, started by, last updated by, last updated at, and draft age.
• FR-138-21 Draft actions: Draft list entries must support explicit resume, explicit non-editable detail or summary access, and may support cancel when authorized.
• FR-138-22 Workspace-shared visibility: Authorized onboarding operators may view resumable drafts within their current workspace for operational continuity.
• FR-138-23 Attribution: The UI must display who started and last updated each resumable draft.
• FR-138-24 Audit coverage: The system must record or preserve meaningful audit events for draft creation, explicit resume, explicit draft selection, confirmed draft updates, provider connection changes, verification start and result persistence, bootstrap initiation, cancellation, completion, and blocked activation override use.
• FR-138-25 Refresh-safe verification semantics: Persisted verification and bootstrap references must survive refresh and revisit, including stale verification indicators where applicable.
• FR-138-26 Activation safety preserved: Refresh and revisit must not bypass existing activation safeguards, blocked-verification override requirements, confirmations, or authorization.
• FR-138-27 Multiple-tab determinism: Same-draft multi-tab usage must be deterministic, with last confirmed write winning while server-side validation protects invariants.
• FR-138-28 Browser regression coverage: Browser tests must validate the hard-refresh experience on a concrete draft URL.
• FR-138-29 Onboarding entry CTA clarity: Entry points that link to /admin/onboarding must label the action according to landing behavior: Add tenant when no resumable draft exists, Continue onboarding when exactly one resumable draft exists, and Choose onboarding draft when multiple resumable drafts exist.
• FR-138-30 Cancellation transition clarity: After cancelling a resumable onboarding draft, the UI must redirect to the canonical draft URL and immediately render the non-editable cancelled summary instead of leaving the operator on the stale editable wizard surface.

Non-Goals

• Keystroke-level autosave of all in-progress inputs.
• Collaborative real-time editing.
• Distributed locking or optimistic locking.
• Cross-workspace draft portability.
• A generic workflow engine abstraction.
• A full onboarding history dashboard beyond draft selection and resume needs.
• Changes to the underlying verification or activation business rules beyond resume semantics.

Assumptions

• TenantOnboardingSession remains the underlying persisted model initially, even if the UX refers to it as an onboarding draft.
• The current onboarding wizard already persists meaningful confirmed state and can be refactored to anchor around explicit draft identity.
• Existing provider verification and activation policies remain in place and are only surfaced more deterministically through draft routing and resume semantics.
• Workspace-scoped operational continuity is preferred over creator-only visibility for resumable drafts.

Dependencies

• Existing managed tenant onboarding wizard page and route registration.
• Existing TenantOnboardingSession model and managed_tenant_onboarding_sessions table.
• Existing provider connection, verification, bootstrap, activation, and audit logging infrastructure.
• Existing workspace membership and onboarding capability enforcement.
• Existing browser and Livewire testing infrastructure.

Contract Interpretation

• The internal contract for this feature defines landing, load, resume, create, and lifecycle semantics for onboarding drafts.
• Existing Filament pages, Livewire handlers, and controller endpoints may satisfy the contract as long as they preserve the documented route, authorization, resume, audit, and fail-closed semantics.
• This spec prefers adapting the current onboarding page and route structure rather than introducing a second wizard implementation.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Onboarding landing	/admin/onboarding	Start new onboarding	Draft list rows when multiple drafts exist	Resume, More	None	Start managed tenant onboarding	None	Continue and Cancel within wizard only	Yes	Auto-redirect is allowed only when exactly one resumable draft exists.
Concrete onboarding draft wizard	/admin/onboarding/{draft}	Resume context actions only	Stepper plus status banner	None	None	Not applicable	Verify, Bootstrap, Activate as already supported	Continue and Cancel	Yes	Sensitive fields stay empty after reload; destructive actions require confirmation; an All onboarding drafts header action is shown only when more than one resumable draft exists so the landing link never no-ops back to the same draft.
Draft picker list	Landing screen when multiple drafts exist	Start new onboarding	Row click-through to detail or resume	Resume, View summary	None	Start new onboarding	None	Not applicable	Yes	Must show attribution, stage, status, and age.
Non-resumable draft summary	Direct access to completed or cancelled draft	View summary	Summary sections	None or policy-approved actions only	None	Return to onboarding landing	None	Not applicable	Yes	Must not re-enter editable wizard mode.

Key Entities (include if feature involves data)

• Onboarding Draft: The workspace-scoped persisted work item currently backed by TenantOnboardingSession, representing confirmed onboarding progress for one target managed tenant.
• Draft Lifecycle State: The resumable or non-resumable state of the draft, at minimum draft, completed, or cancelled.
• Draft State Payload: The confirmed, non-secret persisted state used to derive resume stage, provider references, verification references, bootstrap references, and review notes.
• Resume Context: The operator-facing summary derived from the draft that tells the user what draft is being resumed, its current stage, and who last changed it.
• Draft Selection Result: The explicit operator choice when multiple resumable drafts exist in the workspace.

Success Criteria (mandatory)

Measurable Outcomes

• SC-138-01 Canonical route coverage: In focused route and Livewire coverage, 100% of in-scope draft resume flows operate on /admin/onboarding/{draft} once a concrete draft exists.
• SC-138-02 No silent ambiguity: In focused multi-draft coverage, 100% of landing requests with multiple resumable drafts show draft selection rather than silently choosing a draft or silently resetting to blank Step 1.
• SC-138-03 Durable confirmed progress: In focused refresh coverage, 100% of confirmed Step 1 and Step 2 states restore correctly after a full page reload on the draft URL.
• SC-138-04 Sensitive field protection: In focused refresh coverage, 100% of secret input fields remain non-rehydrated after revisit or hard refresh.
• SC-138-05 Non-resumable safety: In focused lifecycle coverage, 100% of completed or cancelled drafts stay non-editable and do not re-enter active wizard mode.
• SC-138-06 Attribution clarity: In covered multi-operator flows, operators can identify who started and last updated each draft from the picker or draft header.
• SC-138-07 Browser-level trust: Mandatory browser tests pass for hard refresh, revisit, and multi-draft selection on a concrete onboarding draft URL.