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

Research: Managed Tenant Onboarding Draft Identity & Resume Semantics

Decision 1: Use explicit draft identity in the URL

• Decision: Use a hybrid model with /admin/onboarding as a landing route and /admin/onboarding/{onboardingDraft} as the canonical route for an active draft.
• Rationale: This gives operators a concrete mental model, makes refresh deterministic, and removes silent wizard-state heuristics as the primary resume mechanism.
• Alternatives considered:
  • Keep landing-only heuristic resume: rejected because it is ambiguous and not bookmarkable.
  • Query parameter only: acceptable technically, but rejected as the primary enterprise representation because the path route is clearer and easier to reason about.

Decision 2: Resume stage comes from persisted state, not only current_step

• Decision: Derive the resumed wizard step from persisted confirmed data completeness plus verification and bootstrap state.
• Rationale: Persisted data is more trustworthy than a stale step marker and tolerates partial inconsistencies better.
• Alternatives considered:
  • Resume purely from current_step: rejected because it can lie when required state is missing.

Decision 3: Keep unsaved edits transient

• Decision: Persist only at explicit step-confirmation boundaries. Unsaved current-step edits may be lost on refresh.
• Rationale: This keeps the model understandable, avoids partial write complexity, and matches the enterprise requirement that confirmed work be durable without implying autosave.
• Alternatives considered:
  • Autosave every input: rejected as out of scope and higher risk for misleading partial persistence semantics.

Decision 4: Use workspace-shared draft visibility for continuity

• Decision: Authorized onboarding operators in the current workspace may see resumable drafts, regardless of creator.
• Rationale: Enterprise admin workflows require continuity across operators and should not become fragile when one user is unavailable.
• Alternatives considered:
  • Creator-only visibility: rejected because it harms operational continuity and creates unnecessary support burden.

Decision 5: Completed and cancelled drafts are non-resumable

• Decision: Completed and cancelled drafts remain historical or summary records and do not reopen in edit mode.
• Rationale: This avoids unsafe reopening and preserves operator trust around lifecycle meaning.
• Alternatives considered:
  • Allow reopening completed drafts: rejected because it blurs activation completion semantics.

Decision 6: Browser-level validation is mandatory

• Decision: Add browser tests for hard refresh on the canonical draft route.
• Rationale: The main trust defect is visible only in real reload behavior, not just unit or Livewire state transitions.
• Alternatives considered:
  • Feature tests only: rejected because they do not prove real browser reload semantics.