diff --git a/docs/arch/HYPERTWIST_PHASE4_PREPARATION_PACKET_2026-05-06.md b/docs/arch/HYPERTWIST_PHASE4_PREPARATION_PACKET_2026-05-06.md new file mode 100644 index 0000000..f0e94ea --- /dev/null +++ b/docs/arch/HYPERTWIST_PHASE4_PREPARATION_PACKET_2026-05-06.md @@ -0,0 +1,174 @@ +# HyperTwist Phase 4 preparation packet + +Created on `2026-05-06` + +Status: + +- first-party HyperTwist packet +- bounded post-Phase-`3` preparation slice + +## 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.