# HyperTwist roadmap overhaul and expansion guide

Created on `2026-04-26`

Purpose:

- preserve the roadmap-overhaul decision inside the product repo docs root
- make the current planning call visible without needing chat context
- point future planning models or human reviewers to the richer workbook and parse-side planning pack

## 2026-05-11 correction

This file must now be read together with:

- `docs/HT_REPO_INCORPORATION_AUDIT_2026-05-11.md`
- `docs/HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`

## 2026-05-12 restart-authority correction

The canonical cross-location restart reconciliation now lives in:

- `docs/HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md`

Implication:

- older parse-side `Phase 4` continuation docs remain useful lineage for the bounded dashboard-consumer lane that was already landed
- they are not the primary restart authority for the remaining donor portfolio
- the restart authority is now the repo-doc reconciliation plus the `Phase 0R` / `Phase 1R` reset schedule

Current verified truth:

- current curated HyperTwist shallow-eval set: `71` repos
- currently verified live/implemented in checked `UnrealHyperTwist` surfaces: `14`
- permissive already live: `13`
- restrictive already live through proper clean-room implementation: `1`
- the restrictive landed repo is `onionhoney/roux-trainers`
- the remaining `57` are not yet to be treated as already implemented

Implication:

- future roadmap widening must continue from the closed `Phase 0R`, `Phase 1R`, `Phase 2R`, and `Phase 3R-A` through `Phase 3R-F` authority stack rather than from the pre-reset phase ordering
- the correct next move is `Phase 4R-A` for `cubing/cubing.js`, with the optional `Phase 3R-G` browser comparison lane still deferred unless the landed primary browser spatial stack exposes a real gap

## Product-level call

The original HyperTwist roadmap is still valuable.

It should remain preserved as the intent and lineage baseline.

It should not remain the sole live execution authority.

## Why this changed

HyperTwist now has real owned implementation in the Unreal-centered backend across:

- training
- replay
- recognition integration
- coaching
- queueing and scheduling
- timing and analytics
- clean-room governance

That means the product has outgrown a one-line-per-phase roadmap.

## Recommended live planning layer

Use five planning surfaces:

1. preserved historical roadmap baseline
2. roadmap invariants
3. live execution roadmap
4. feature-set matrix
5. model role and provider matrix

## Timing call

Now is a good time for the overhaul because:

- the backend is real enough to anchor planning
- the repo state is clean
- multi-model expansion has not yet been allowed to reshape architecture

## Main rule for model expansion

Define roles first.

Evaluate providers second.

Integrate providers only after the roles and feature-set map exist.

Current correction call from the source-exposed audit, current execution refresh, and 2026-05-11 implementation-truth correction:

- preserve the roadmap direction
- update the canonical planning docs so they reflect:
  - the verified implementation truth that `14` of the current `71` HyperTwist repos are live right now in checked Unreal surfaces
  - the fact that `13` of those `14` are permissive lanes
  - the fact that `onionhoney/roux-trainers` is the only currently verified restrictive repo that was properly clean-roomed and then implemented
  - the fact that the remaining `57` are still not live, with `45` active implementation-board rows plus `9` retained benchmark/oracle rows outside that board
  - the reconciled `14`-family feature set
  - manifest and custody governance gaps
  - pre-Phase-5 speech governance gates
  - retained benchmark-oracle and mirror-intake reservations
  - current code reality in which training/coaching/catalog integration is materially ahead of recognition and hypercube runtime implementation
  - the imported generated-mode gap is closed; request/config/selection plumbing and the bounded clean-room executor are already landed in first-party code
  - the latest landed bounded `Phase 4` packet closes the retained-idle comparison/outcome actionability gap at the end of the recognition-assisted coach-to-review continuity lane, and the final retained-surface confirmation pass now leaves that closure lane functionally complete
  - the retained idle widget surface now keeps retained comparison and decision history inspectable without continuing to advertise live launch or guidance-outcome actions once the coach-to-review loop has already collapsed to truthful closed-loop idle
  - the now-complete deliberate `UHyperTwistTrainingRuntimeLibrary` world-context consumer lane reaches through active generated-mode selector option owned-execution split-phase current-selection merged ordered roster phase-id lookup, normalized-order lookup, and evaluation-order lookup inspect surfaces, so gameplay/Blueprint callers can inspect one retained merged-roster row directly by phase id, normalized order, or evaluation order without scanning the merged roster array or re-running inspect derivation details directly
  - the latest landed bounded `Phase 4` packet stays adjacent in that same retained-history dashboard lane and adds the dedicated method-drill recovery memory history status/detail inspect pair over the exact displayed retained-history lines already shown by the widget, so gameplay/Blueprint callers can inspect the current retained drill-recovery-memory text band directly without scraping text blocks or routing only through the broader selected-history and navigation surfaces
  - the latest landed bounded `Phase 4` packet also closes the adjacent preferred template-launch plus recommended/follow-up preview action control band with a single composite inspect seam over those three already-landed action surfaces, so gameplay/Blueprint callers can inspect that whole action cluster without stitching three separate action getters together
  - the latest landed bounded `Phase 4` packet deliberately chooses the next adjacent live dashboard consumer band and adds a single composite execution-action-control seam over attempt-result action enablement, run-control enablement, and queue-action enablement, so gameplay/Blueprint callers can inspect that whole execution-control cluster without stitching three separate control surfaces together
  - the latest landed bounded `Phase 4` packet deliberately chooses another adjacent live dashboard consumer band and adds a single composite verification / recognition / review-policy seam over the already-landed verification action, repository verification status, recognition status, and review-policy status surfaces, so gameplay/Blueprint callers can inspect that whole status cluster without stitching four adjacent getters together
  - the latest landed bounded `Phase 4` packet deliberately chooses another adjacent live dashboard consumer band and adds a single composite selected-queue seam over the already-landed selected-queue navigation, start-selected action, selected-queue summary, and selected queue-entry detail surfaces, so gameplay/Blueprint callers can inspect that whole queue-focused dashboard cluster without stitching four adjacent getters together
  - the latest landed bounded `Phase 4` packet deliberately chooses another adjacent live dashboard consumer band and adds a single queue scheduling / recovery seam over the already-landed queue counts / status, schedule horizon, schedule policy / friction, and queue recovery live status/detail surfaces, so gameplay/Blueprint callers can inspect that whole scheduling-and-recovery dashboard cluster without stitching five adjacent getters together
  - the latest landed bounded `Phase 4` packet deliberately chooses another adjacent live dashboard consumer band and adds a single closure-recovery seam over the already-landed closure-recovery live status/detail and closure-recovery history navigation surfaces, so gameplay/Blueprint callers can inspect that whole closure-recovery dashboard cluster without stitching three adjacent getters together
  - the latest landed bounded `Phase 4` packet deliberately chooses another adjacent live dashboard consumer band and adds a single queue-suppression seam over the already-landed queue-suppression live summary/detail and queue-suppression history navigation surfaces, so gameplay/Blueprint callers can inspect that whole queue-suppression dashboard cluster without stitching three adjacent getters together
  - the latest landed bounded `Phase 4` packet deliberately chooses the next adjacent live dashboard consumer band in the current-case / timer neighborhood and adds a single current-case-timer seam over the already-landed active-attempt timer, current-case/deck status, attempt-time hint, live timer split control, and attempt-review navigation surfaces, so gameplay/Blueprint callers can inspect that whole current-case/timer dashboard cluster without stitching five adjacent getters together
  - with the retained-history text-band lane, the template-launch / preview action-control band, the execution-action-control band, the verification / recognition / review-policy status band, the selected-queue band, the queue scheduling / recovery band, the closure-recovery band, the queue-suppression band, the handoff-history band, the guidance-decision-history band, the template-launch-history band, the method-drill recovery-outcome-history band, the method-drill recovery-memory-history band, the method-drill follow-up-history band, the method-drill operational band, the guidance-preview band, the guidance-reasoning band, the run-state recap band, the handoff-transition band, and the current-case timer band now all closed baseline, the next best clean move is to deliberately choose another adjacent live dashboard consumer band rather than reopen already-landed surfaces by drift
  - the current execution-discipline rule that broad refactor / monolith-splitting work should not interrupt the active bounded roadmap packet unless structure is actually blocking it

## Donor portfolio phase taxonomy

- unrelated repos are omitted
- duplicate, inferior, redundant, or clearly superseded repos are omitted
- selected high-value permissive repos are not just inspiration; they are intended full implementation targets inside first-party HyperTwist, executed packet by packet rather than through one bulk import event
- selected high-value restrictive repos are not just archival references; they are intended clean-room implementation targets when they remain selected after portfolio triage
- donor or reference status does not by itself mean a selected repo is discarded; selected repos may still be full implementation targets, bounded donor lanes, bounded clean-room lanes, or benchmark/reference lanes depending on phase and licensing posture
- repo-portfolio intake/classification, mirror custody boundaries, model allowlists, and repo-by-repo deep source integration closure are now closed through `Phase 0R` and `Phase 1R` for the current retained set, but the remaining `57` non-live rows still require packet-disciplined widening
- owned contract extraction from chosen donors is materially present in landed first-party code, but the contract/handoff layer now needs a deliberate `Phase 1R` overhaul so it reflects only the verified landed set plus the retained post-evaluation backlog
- portfolio-level sorting/classification is largely done, but deep source-level audit of every still-selected repo is not globally closed and must now be resumed as a first-class reset packet rather than treated as incidental background work
- clean-room work belongs first to governance and contract shaping, then to bounded first-party implementation; at the moment, `onionhoney/roux-trainers` is the only currently verified restrictive repo that has both a proper clean-room chain and a landed implementation surface
- implementation of selected repo value is intentionally distributed by domain across later phases rather than treated as one giant repo-import pass:
  - Phase `3` / `4`: coaching, runtime, orchestration, recognition continuity, and live consumers
  - Phase `5`: speech-sidecar and embodied-coach donors
  - Phase `6`: hypercube/simulation donors
  - Phase `7`: XR/immersive donors
  - Phase `8`: benchmark-oracle, correctness, and release-hardening donors
- before new donor-shaped widening resumes beyond the already landed six-live-repo reality, do treat the remaining selected mirror portfolio as a mandatory repo deep source integration evaluation backlog that must be actively closed through `Phase 0R` and `Phase 1R`

## Current execution-reality references

For the current code-reality synthesis and active phase-discipline note, also read:

- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\116-hypertwist-handoff.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\119-hypertwist-current-execution-reality-and-phase-discipline.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\122-hypertwist-phase-0r-restart-authority-and-sequencing.md`
- `C:\HyperTwist\docs\arch\HYPERTWIST_PI_PRIMING_FINDINGS_2026-05-04.md`
- `C:\HyperTwist\docs\HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`
- `C:\HyperTwist\docs\HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md`

## Higher-detail planning references

For the fuller planning pack, read:

- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\92-hypertwist-roadmap-overhaul-planning-layer.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\93-hypertwist-roadmap-overhaul-document-map.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\94-hypertwist-roadmap-overhaul-model-prompts.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\95-hypertwist-roadmap-invariants.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\96-hypertwist-live-execution-roadmap.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\97-hypertwist-feature-set-matrix.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\98-hypertwist-model-role-and-provider-matrix.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\99-hypertwist-roadmap-expansion-established-insights.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\roadmap-overhaul-pack\outputs\abc-phase-2-reconciled-roadmap-expansion.md`
- `C:\visual_studio_solutions\multi_project\GPT 5.4 HyperTwist parse\roadmap-overhaul-pack\outputs\source-exposed-audit-reconciled.md`
- `C:\Workspaces\HyperTwist\implementation-workspaces\scratch\roadmap-bootstrap\docs\architecture\roadmap-overhaul-and-expansion-readiness.md`
- `C:\Workspaces\HyperTwist\implementation-workspaces\scratch\roadmap-bootstrap\docs\architecture\roadmap-expansion-pack-checkpoint.md`

## Safety rule

This overhaul should stay documentation-first until the new planning layer is accepted.
