user-engine/workplans/USER-WP-0013-onboarding-journeys-and-welcome-protocols.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, depends_on, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	depends_on	state_hub_workstream_id
USER-WP-0013	workplan	Onboarding Journeys And Welcome Protocols	netkingdom	user-engine	finished	codex	netkingdom	medium	13	2026-06-15	2026-06-15	USER-WP-0011 USER-WP-0012	1dc82dfd-be68-4585-b6c9-6d24aebd3e27

USER-WP-0013 - Onboarding Journeys And Welcome Protocols

Goal

Create a journey layer that helps newly registered or newly entitled users enter the right NetKingdom subsystems. Welcome protocols should be driven by registration, prepared-account, invitation, role, profile, and access events.

Scope Direction

user-engine owns journey state, task references, event correlation, and user context. Delivery systems, protected services, help content, notification channels, and external task systems remain adapters or downstream systems.

Non-Goals

• Do not build a notification platform.
• Do not embed service-specific tours or support content in core domain code.
• Do not replace external workflow/task systems.
• Do not build the UI in this workplan.

Tasks

id: USER-WP-0013-T1
status: done
priority: high
state_hub_task_id: "30ef8507-eebc-4b96-8aa6-c530bef05739"

Define onboarding journey, welcome protocol, journey step, task, and subsystem handoff models.

id: USER-WP-0013-T2
status: done
priority: high
state_hub_task_id: "7c6e53d4-ff96-4036-a413-f04b4b73d266"

Add journey templates keyed by registration outcome, prepared entitlement, tenant, realm, service, application, role, hat, and factor requirements.

id: USER-WP-0013-T3
status: done
priority: high
state_hub_task_id: "d9c2983a-45d1-4b1b-a416-63e180ca74b3"

Implement journey start, progress, complete, skip, fail, and resume operations with authorization, audit, and outbox behavior.

id: USER-WP-0013-T4
status: done
priority: medium
state_hub_task_id: "7155c2eb-4e32-46f0-ad33-961784cb9a03"

Add adapter ports for notifications, task systems, support content, subsystem welcome callbacks, and lifecycle task linking.

id: USER-WP-0013-T5
status: done
priority: medium
state_hub_task_id: "c5e42dd6-207a-4b1e-a0d8-35701e9f71bc"

Expose onboarding status through identity context, diagnostics, and optional UI contracts.

Acceptance Criteria

• Registration or prepared-account claim can start an onboarding journey.
• Journey state is resumable, auditable, and correlated with outbox events.
• Subsystem welcome steps are adapter-driven, not hard-coded into core registration logic.
• Users and admins can inspect pending onboarding work and blocked steps.
• Missing subsystem callbacks produce explicit lifecycle gaps.

Expected Outputs

• Onboarding journey domain model.
• Welcome protocol service facade.
• Adapter ports for notifications and subsystem handoff.
• Scenario tests for successful, blocked, and resumed onboarding.

Implementation Notes

Implemented on 2026-06-15:

• Added OnboardingTriggerType, OnboardingJourneyStatus, OnboardingStepStatus, WelcomeProtocol, WelcomeProtocolStep, OnboardingJourney, OnboardingStep, OnboardingTask, and SubsystemHandoff domain models.
• Added welcome-protocol and onboarding-journey persistence to UserEngineStore and InMemoryUserEngineStore, including transaction snapshots and record counts.
• Added adapter ports for onboarding notifications, task links, support content, subsystem welcome callbacks, and lifecycle task linking.
• Added UserEngineService onboarding facade methods: register_welcome_protocol, list_welcome_protocols, start_onboarding_journey, start_onboarding_for_registration, start_onboarding_for_prepared_account, progress_onboarding_step, complete_onboarding_step, skip_onboarding_step, fail_onboarding_step, resume_onboarding_journey, and onboarding_diagnostics.
• Added auto-start hooks for matching registration-completion protocols and prepared-account claim protocols.
• Extended identity_context with onboarding journeys for the resolved user/tenant.
• Added lifecycle-gap handling for missing subsystem callbacks and resumable blocked/failed journey state.
• Added docs/onboarding-journeys-and-welcome-protocols.md, public contract updates, and tests for registration-triggered, prepared-claim-triggered, blocked, resumed, progressed, skipped, and failed onboarding.

Verification:

make test
Ran 66 tests in 0.620s
OK