# HyperTwist — DEVELOPMENT.md

## Development philosophy

HyperTwist should be developed as a serious native product:
- Unreal project as the main runtime
- C++ simulation and rendering core
- Blueprints for interaction and curriculum logic
- bounded CV or analytics sidecars where needed
- minimal web-only surface

## Current development gate

Do not reopen broad donor-driven widening as if the whole retained portfolio were already settled.

Current truth:

- `18` repos are currently verified live in checked Unreal surfaces
- `13` are permissive `MIT` or `Apache-2.0`
- `4` are boundary-sensitive lanes: `cubing/cubing.js` through the practical `MPL` adapter path, `cutelyaware/magiccube4d` through the landed attribution/provenance boundary path, `google/model-viewer/packages/shared-assets` through the landed allowlist/provenance boundary path, and `PostHog/posthog` through the landed control-plane subtree-boundary path
- `1` is the restrictive `onionhoney/roux-trainers` lane that is already properly clean-roomed and implemented
- `Phase 0R` is now closed for the remaining `53` non-live rows
- `Phase 1R` is now closed as the retained-set contract and handoff overhaul
- `Phase 2R` is now closed as the retained-set ownership and acceptance packet sequence
- `Phase 3R-A` is now closed as the landed `Aarav2709/KubeTimr` widening packet
- `Phase 3R-B` is now closed as the landed `Hypercubers/hypercubing.xyz` widening packet
- `Phase 3R-C` is now closed as the landed `apache/echarts` widening packet
- `Phase 3R-D` is now closed as the landed `google/model-viewer` widening packet
- `Phase 3R-E` is now closed as the landed `met4citizen/TalkingHead` widening packet
- `Phase 3R-F` is now closed as the landed `mrdoob/three.js`, `pmndrs/react-three-fiber`, and `pmndrs/xr` widening packet
- `Phase 4R-A` is now closed as the landed `cubing/cubing.js` classic-cubing adapter widening packet
- `Phase 4R-B` is now closed as the landed `cutelyaware/magiccube4d` legacy `4D` interaction/history/macro widening packet
- `Phase 4R-C` is now closed as the landed `google/model-viewer/packages/shared-assets` allowlist/provenance widening packet
- `Phase 4R-D` is now closed as the landed `PostHog/posthog` control-plane widening packet

## Model A interpretation rule

For boundary-sensitive and restrictive rows:
- future `Model A` work should still pursue full bounded realization of the retained domain
- `do not promote` and similar wording in the `0R` packets is a boundary filter, not a cap on later source-value extraction depth
- if a retained handoff is too thin, strengthen the packet or scrubbed handoff while preserving the no-copy guardrails

Canonical doctrine doc:
- `C:\HyperTwist\docs\HYPERTWIST_MODEL_A_MAX_VALUE_EXTRACTION_MODUS_OPERANDI_2026-05-13.md`

Next sequence:

1. preserve the eighteen landed lanes
2. preserve the landed `cubing/cubing.js` boundary-sensitive adapter lane with its `MPL` notice posture explicit
3. preserve the landed `cutelyaware/magiccube4d` boundary-sensitive lane with its attribution, upstream-link, and provenance posture explicit
4. preserve the landed `google/model-viewer/packages/shared-assets` boundary-sensitive lane with its allowlist, review-only, and local-only posture explicit
5. preserve the landed `PostHog/posthog` boundary-sensitive lane with its explicit root-`MIT`-core-versus-`ee/` subtree boundary explicit
6. use the retained-set contract as the only legal/roadmap routing surface for non-live rows
7. keep `Aarav2709/KubeTimr`, `Hypercubers/hypercubing.xyz`, `apache/echarts`, `google/model-viewer`, `met4citizen/TalkingHead`, `cubing/cubing.js`, `cutelyaware/magiccube4d`, `google/model-viewer/packages/shared-assets`, and `PostHog/posthog` on preserve-and-enhance footing through their landed packets
8. continue broader widening from `Phase 4R-E`, with optional `Phase 3R-G` comparison work only if the landed primary browser spatial stack exposes a real gap

## Suggested repo structure

- `HyperTwist/`
  - `Source/HyperTwistCore`
  - `Source/HyperTwistSimulation`
  - `Source/HyperTwistRecognition`
  - `Source/HyperTwistReplay`
  - `Source/HyperTwistTraining`
  - `Source/HyperTwistCoach`
  - `Source/HyperTwistXR`
- `hypertwist-services/`
  - optional CV inference service
  - optional progression or coaching service
- `docs/`
  - replay packet specs
  - trainer logic
  - notation / interchange specs
  - benchmark notes

## Build order

1. preserve and document landed implementation truth
2. completed `Phase 0R` deep source evaluation reset for remaining rows
3. completed `Phase 1R` contract / handoff / provenance overhaul
4. completed retained-set ratification and packet design
5. permissive implementation waves from retained rows
6. boundary-sensitive adapter or sidecar waves
7. restrictive clean-room waves from retained rows
8. simulation core expansion from retained set
9. state and notation standardization
10. replay and export
11. physical recognition
12. trainer/progression
13. AI coach
14. immersive hyper modes
15. optimization and polish

## Testing

- move/state correctness
- replay integrity
- scramble validity
- CV uncertainty handling
- coaching recommendation stability
- XR interaction reliability
- progression persistence and analytics
