# HyperTwist — ROADMAP.md

## Current execution gate

Before widening new HyperTwist donor-driven implementation beyond the already landed lanes, preserve this current truth:

- current shallow-eval set: `71` repos
- currently verified live/implemented in checked Unreal surfaces: `18`
- permissive live lanes: `13`
- boundary-sensitive live lanes: `4`
- restrictive live lane: `1`
- the restrictive landed lane is `onionhoney/roux-trainers`, and it is to be treated as properly clean-roomed and then 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` timer subsystem widening packet
- `Phase 3R-B` is now closed as the landed `Hypercubers/hypercubing.xyz` knowledge and community-reference widening packet
- `Phase 3R-C` is now closed as the landed `apache/echarts` analytics and reporting widening packet
- `Phase 3R-D` is now closed as the landed `google/model-viewer` browser presentation, compact editor, and standards-aware asset-QA widening packet
- `Phase 3R-E` is now closed as the landed `met4citizen/TalkingHead` embodied companion, narration, lip-sync, gesture, subtitle, and avatar-embed widening packet
- `Phase 3R-F` is now closed as the landed `mrdoob/three.js`, `pmndrs/react-three-fiber`, and `pmndrs/xr` browser spatial support widening packet
- `Phase 4R-A` is now closed as the landed `cubing/cubing.js` classic-cubing semantic/runtime adapter widening packet
- `Phase 4R-B` is now closed as the landed `cutelyaware/magiccube4d` legacy `4D` interaction/history/macro/provenance widening packet
- `Phase 4R-C` is now closed as the landed `google/model-viewer/packages/shared-assets` fixture allowlist/provenance widening packet
- `Phase 4R-D` is now closed as the landed `PostHog/posthog` control-plane subtree-boundary widening packet

Current routing truth:

- retained rows total: `68`
- discarded from the active retained set: `3`
- active non-live implementation-board rows: `41`
- retained benchmark, oracle, or clean-room-later rows outside the active implementation board: `9`

The next bounded move is `Phase 4R-E`, with the optional `Phase 3R-G` browser comparison lane deferred unless the landed primary browser spatial stack exposes a real gap.

## Reset phases

### Phase `0R` — remaining repo deep evaluation

- close the implementation-truth gap for the remaining `65`
- decide keep / promote / demote / benchmark / discard
- decide direct permissive, bounded dependency, clean-room, or reference-only lane

### Phase `1R` — contract and handoff overhaul

- update license tracking
- update roadmap and handoff docs
- update repo-row boards
- refresh clean-room and Model B boundaries
- rebuild later implementation waves from the retained set only

Status:

- closed on `2026-05-13`
- authority doc:
  - `docs/HYPERTWIST_PHASE_1R_RETAINED_SET_CONTRACT_AND_HANDOFF_2026-05-13.md`

### Phase `2R` — retained-set ratification

- freeze the post-`Phase 0R` retained set into an implementation-ready board
- define packet classes, subsystem entry points, and ownership

### Phase `3R` — permissive implementation waves

- execute retained straight-permissive rows first
- prioritize the retained architecture anchors and high-value donor lanes that can become owned capability quickly

### Phase `4R` — boundary-sensitive adapter and sidecar waves

- resolve the retained `MPL`, mixed-term, asset-term, enterprise-slice, and commercial-boundary rows
- prefer bounded adapter or sidecar use where the retained posture says that is the cleaner path

### Phase `5R` — restrictive clean-room waves

- refresh Model A / Model B chains for retained restrictive rows
- implement only from the refreshed clean-room handoff materials

### Phase `6R` — retained-set capability widening

- widen simulation, recognition, XR, and support-plane work only from the retained evaluated set

### Phase `7R` — benchmark, discard, and hardening closure

- close oracle/reference/discard decisions
- tie retained benchmark rows to validation and release-hardening

## A — Alignment
Freeze terminology, repo roles, and dual-pillar architecture.

## B — Base simulation runtime
Stand up Unreal runtime, puzzle-state core, and core rendering loop.

## C — Cube-state / notation layer
Standardize notation, scramble, replay packets, and interchange.

## D — Detection and reconstruction
Integrate camera/CV and confidence-aware reconstruction.

## E — Replay and explainability
Build replay surfaces, timing analysis, and explanatory overlays.

## F — Foundational training
Drills, timers, analytics, curriculum, and method-aware progression.

## G — General AI coach
Commentary, drill planning, and personalized progression support.

## H — Hyper engine deepening
Expand higher-dimensional support, projection, and advanced workflows.

## I — Immersive interaction
XR modes, puzzle manipulation, and spatial tutorial flows.

## J — Validation and benchmarking
Correctness, replay integrity, performance, and benchmark harnesses.

## K — Knowledge and curriculum
Guided ladders from beginner through hypercubing expertise.

## L–Z
Continue event expansion, export, community-facing surfaces, optimization, enterprise/education variants, and release hardening.
