Freeze Phase 4 preparation order

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.