# HyperTwist Phase 4 preparation packet

Created on `2026-05-06`

Status:

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

## 2026-05-20 authority refresh

This preparation packet is no longer the live next-step authority.

The two ordered Phase `4` packets it named are now confirmed landed in current code:

- `d4f4ad3` `Add primary coach orchestration entry lane`
- `1860f14` `Add provider-backed recognition sidecar client`

The related runtime recognition handoff lane is also live in current first-party training code.

Use this document as:

- the historical sequencing rationale for why orchestration preceded recognition

Do not use it as:

- proof that the orchestration packet is still open
- proof that recognition productionization is still the next bounded move

Current standing truth 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`
- `docs/REPO_LICENSE_TRACKING.md`

## Purpose

This packet opens the explicit post-Phase-`3` preparation lane after:

- the Phase `3` end-state freeze packet landed
- the thin generated-mode runtime consumer packet landed
- the final dashboard generated-mode consumer convergence packet landed

The open task is:

- freeze the Phase `4` start order and guardrails so the next implementation lane begins deliberately instead of by drift

It is not:

- a live recognition-provider integration packet
- a broad orchestration rewrite
- a speech or simulation packet
- a cleanup-only planning rewrite

## Scope

Bounded lane:

- define the first implementation order for post-Phase-`3` work
- identify the real first file surfaces for that order
- record what remains preparatory versus what should wait for the first actual Phase `4` implementation packet

Required result:

- the repo has one explicit product-side packet naming the first Phase `4` start order
- the packet distinguishes orchestration-first work from later recognition-provider work
- the packet preserves the roadmap reservations that matter before Phase `4` widens materially

Out of scope:

- implementing the first Phase `4` code packet itself
- provider-specific CV integration
- changing the already-closed Phase `3` generated-mode backend
- broad roadmap rewording outside the current continuation docs

## Current owned product truth

The current first-party product now has:

- closure-complete Phase `3` training/coaching backend work
- durable repository save/load/repair/integrity coverage across the active coaching stack
- bounded imported generated-mode selection, request creation, persistence, query, inspection, and owned execution
- thin generated-mode consumer parity through:
  - `UHyperTwistTrainingPanelWidget`
  - `AHyperTwistTrainingSessionActor`
  - `UHyperTwistCoachDashboardWidget`

The current missing work is no longer Phase `3` closure debt.

The missing work is post-closure productionization:

- production-oriented runtime orchestration
- provider-backed recognition execution beyond the current mock surface

## Phase 4 start-order decision

The first Phase `4` implementation packet should be:

1. `orchestration-first`

The second Phase `4` implementation packet should be:

2. `recognition productionization over the existing vision contract`

## Why orchestration comes first

Current code reality:

- the training/coaching backend is already materially mature
- the main runtime entry points are already spread across the subsystem, runtime library, panel widget, session actor, and coach dashboard widget
- the recognition client surface is still interface-and-mock level, not provider-backed runtime productionization

That means the stronger first move is:

- stabilize the production-facing orchestration entry lane over the already-closed backend

before:

- wiring a real recognition provider into runtime behavior that still lacks its final orchestration posture

## Strongest first implementation targets for the first Phase 4 packet

### Orchestration entry surfaces

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistTraining/HyperTwistTrainingSubsystem.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistTrainingSubsystem.cpp`
  - active run start / continue / submit / complete / clear surfaces
  - coach-run launch surfaces
  - queue-entry launch surfaces
- `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/Public/HyperTwistTraining/HyperTwistCoachDashboardWidget.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistTraining/HyperTwistCoachDashboardWidget.cpp`

### Recognition-provider follow-on surfaces

- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistRecognition/HyperTwistVisionClient.h`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Private/HyperTwistRecognition/HyperTwistMockVisionClient.cpp`
- `UnrealHyperTwist/Source/UnrealHyperTwist/Public/HyperTwistRecognition/HyperTwistRecognitionTypes.h`

## Strongest first goal for the first Phase 4 implementation packet

The first actual Phase `4` code packet should:

- define one clearer production-facing orchestration lane for starting, continuing, and finalizing runtime training/coaching flows
- avoid reopening already-closed generated-mode backend work
- give later recognition integration one stable place to plug in

It should not yet:

- bring in a provider-specific recognition stack
- widen into speech, simulation, or XR
- perform large structural cleanup for its own sake

## Planning reservations that remain visible

These still matter before Phase `4` widens materially:

1. manifest reconciliation and custody governance for restrictive mirrors and clean-room linkage
2. explicit handling of the retained supplemental mirror queue

Current decision:

- keep those reservations visible
- do not let them block the first bounded orchestration packet unless that packet directly depends on them

## Suggested next packet

The next explicit implementation packet after this preparation slice should be:

- a bounded `Phase 4 orchestration entry packet`

The packet should be framed as:

- production-oriented run orchestration over the stabilized subsystem/runtime/consumer layers

## Suggested file ownership

Primary edit surface:

- `docs/arch/HYPERTWIST_PHASE4_PREPARATION_PACKET_2026-05-06.md`

## Acceptance criteria

- the packet states the first Phase `4` implementation order
- the packet explains why orchestration should precede recognition-provider work
- the packet records the strongest first file surfaces for that order
- the packet preserves the roadmap reservations without turning them into blanket blockers

## Validation checklist

1. read the packet against the current product code reality
2. confirm it does not reopen Phase `3` closure work
3. confirm it names Phase `4` implementation order concretely enough for the next session

That is the packet.
