# HyperTwist Phase 4 orchestration entry packet

Created on `2026-05-06`

Status:

- first-party HyperTwist packet
- bounded post-Phase-`3` implementation slice

## 2026-05-20 authority refresh

This packet is already landed in current code.

Code authority:

- `d4f4ad3` `Add primary coach orchestration entry lane`
- follow-on UI/consumer surface alignment:
  - `440cf06` `Expose gameplay primary coach CTA surface`

Current product evidence includes:

- `UHyperTwistTrainingSubsystem::StartPrimaryCoachAction(...)`
- runtime-library wrappers for that action
- panel-widget and session-actor wrappers for that action
- dashboard and coach-library surfaces aligned to the same primary coach action order

Use this document as:

- the bounded scope and ownership rationale for the landed orchestration lane

Do not use it as:

- proof that `Phase 4` orchestration entry is still the next open packet

Current standing route after this landed packet now lives in:

- `docs/arch/HYPERTWIST_PHASE6R_A_HYPERSPEEDCUBE_RUNTIME_ANCHOR_PREPARATION_PACKET_2026-05-20.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md`

## Purpose

This packet starts Phase `4` with an orchestration-first slice over the already-closed training/coaching backend.

The open task is:

- expose one production-facing primary coach orchestration action above the existing low-level coach-run launch methods

It is not:

- a recognition-provider packet
- a generated-mode backend packet
- a dashboard redesign
- a broad runtime refactor

## Scope

Bounded lane:

- create one first-party primary coach orchestration entry action in the subsystem and runtime library
- surface that action through the generic panel widget and session actor consumers
- make the dashboard use that orchestration action instead of owning the launch-choice branching itself

Required result:

- the repo has a stable first-class action for:
  - launch next queued coach work when runnable
  - otherwise launch follow-up work when available
  - otherwise launch recommended work when available
- dashboard, panel widget, and session actor can all consume that same orchestration action

Out of scope:

- timer-phase orchestration
- provider-backed recognition integration
- new queue heuristics
- changes to generated-mode request/execution behavior

## Current owned product truth

These pieces are already live:

- low-level coach launch primitives:
  - recommended
  - follow-up
  - next queued
  - selected queue entry
- consumer surfaces over those primitives in:
  - runtime library
  - panel widget
  - session actor
  - dashboard widget

What was still missing:

- one explicit orchestration action above those low-level primitives
- removal of dashboard-local branching as the only place where the primary coach launch order existed

## Implementation target

The slice should do the following:

1. add `StartPrimaryCoachAction(...)` to the training subsystem
2. add the matching runtime-library wrapper
3. add matching thin wrappers to the panel widget and session actor
4. update the dashboard widget to call that action instead of hand-owning the queued / follow-up / recommended branching

## Suggested file ownership

Primary edit surfaces:

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSubsystem.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSubsystem.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingRuntimeLibrary.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingPanelWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingPanelWidget.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSessionActor.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSessionActor.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistCoachDashboardWidget.cpp`
- `docs/arch/HYPERTWIST_PHASE4_ORCHESTRATION_ENTRY_PACKET_2026-05-06.md`

## Acceptance criteria

- one first-party primary coach orchestration action exists above the low-level launch primitives
- dashboard launch branching uses that action
- panel widget and session actor surface that action too
- full UE build still succeeds

## Validation checklist

1. build `UnrealHyperTwist.sln`
2. confirm dashboard launch branching now routes through the orchestration action
3. confirm panel widget and session actor expose the same action

That is the packet.
