hypertwist/docs/HYPERTWIST_ROADMAP_OVERHAUL_EXPANSION_GUIDE.md

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.