scriptoriumadmin/hypertwist
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Deepen HyperTwist Phase 0R-A source evaluation

Browse source
This commit is contained in:
axiomlogicnexus 2026-05-12 22:44:52 +02:00
parent 4191ec9ab0
commit 6ef49941cf
4 changed files with 429 additions and 166 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md
View file

@ -111,19 +111,22 @@ For restart and future widening decisions, use this order:
1. `docs/HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md`
2. `docs/HT_REPO_INCORPORATION_AUDIT_2026-05-11.md`
3. `docs/HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`
4. `docs/HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md`
5. `docs/REPO_LICENSE_TRACKING.md`
6. `docs/v6_5_deep_manual_pack/README.md`
7. `docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md`
8. `docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md`
9. safe parse/workbook governance docs:
4. packet-level deep-source authority docs for any repo being implemented:
- `docs/HYPERTWIST_PHASE_0R_PACKET_0R_A_EVALUATION_2026-05-12.md`
- later `Phase 0R` packet docs as they are upgraded to the same standard
5. `docs/HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md`
6. `docs/REPO_LICENSE_TRACKING.md`
7. `docs/v6_5_deep_manual_pack/README.md`
8. `docs/v6_5_deep_manual_pack/HyperTwist/ROADMAP.md`
9. `docs/v6_5_deep_manual_pack/HyperTwist/DEVELOPMENT.md`
10. safe parse/workbook governance docs:
- `06-project-agnostic-repo-evaluation-modus-operandi.md`
- `07-benchmark-oracle-vs-clean-room-implementation.md`
- `88-roadmap-implementation-workbook.md`
- `89-phase-0-and-phase-1-bootstrap-packet.md`
- `90-clean-room-safe-project-context.md`
- `122-hypertwist-phase-0r-restart-authority-and-sequencing.md`
10. the current v6.3 CSV boards and prompts
11. the current v6.3 CSV boards and prompts
Use the following only as lineage or historical context unless a restart doc explicitly points back to them:
@ -143,6 +146,22 @@ Required standing rules:
- preserve `onionhoney/roux-trainers` as the only currently verified landed restrictive clean-room lane
- do not collapse `selected`, `retained`, `integrate`, `repurpose`, or `donor bench` into `already implemented`
- do not widen new donor-shaped implementation from the remaining `65` until `Phase 0R` and `Phase 1R` close
- before implementing any retained repo, read the packet-level deep-source authority doc for that repo class if one exists
## 2026-05-12 packet-depth correction
`Packet 0R-A` was originally closed correctly as a retained-set packet, but too shallowly.
Current correction:
- `docs/HYPERTWIST_PHASE_0R_PACKET_0R_A_EVALUATION_2026-05-12.md` is now the deep-source integration authority for the seven `0R-A` repos
- it records what source was actually read, what value must be salvaged, and why any surface is not promoted
- future `Phase 0R` packets should use the same standard rather than only describing keep/discard posture
Practical implication:
- if a future instance is about to integrate `Hyperspeedcube`, `qbr`, `rubix-cube-solver`, `KubeTimr`, `MagicTile`, `Magic120Cell`, or `MagicCube5D`, it should not start from the shallow CSV row or bucket label
- it should start from `0R-A`, then check `REPO_LICENSE_TRACKING.md`, then return to the schedule
## Restart phase sequence

534
docs/HYPERTWIST_PHASE_0R_PACKET_0R_A_EVALUATION_2026-05-12.md
View file

@ -1,21 +1,33 @@
# HyperTwist Phase 0R Packet 0R-A Evaluation
# HyperTwist Phase 0R Packet 0R-A Deep Source Evaluation
Created on `2026-05-12`
## Status
`Packet 0R-A` remains `closed` as a `Phase 0R` evaluation packet.
This rewrite replaces the earlier shallow `0R-A` wording with the actual standard required for future implementation work:
- read the upstream source directly
- salvage all meaningful value
- omit only when the surface is:
- an inferior duplicate
- superseded by a stronger retained donor
- off topic to HyperTwist's retained product scope
- host-shell glue with no durable architecture value
- record the rationale every time something is not promoted
For these seven repos, this document is now the canonical `integration-facing` authority.
Before a future instance implements any `0R-A` repo, it must read:
1. this document for source-value extraction and exclusion rationale
2. [REPO_LICENSE_TRACKING.md](C:/HyperTwist/docs/REPO_LICENSE_TRACKING.md:1) for license, attribution, notice, and provenance obligations
3. [HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md](C:/HyperTwist/docs/HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md:1) for sequencing
## Purpose
This document closes the first `Phase 0R` evaluation packet for the seven architecture-anchor permissive repos that were explicitly scheduled as `Packet 0R-A` in the restart reconciliation.
It answers, for each repo:
- whether it survives the `Phase 0R` retained-set reset
- whether it is already live in checked Unreal surfaces
- what implementation lane it should take if retained
- when it should be scheduled in the restart sequence
## Packet scope
This packet evaluates:
This packet redoes `Phase 0R-A` as a true deep source parsing packet for:
- `HactarCE/Hyperspeedcube`
- `kkoomen/qbr`
@ -25,237 +37,441 @@ This packet evaluates:
- `roice3/Magic120Cell`
- `roice3/MagicCube5D`
These are the exact repos named as `Packet 0R-A` in [HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md](C:/HyperTwist/docs/HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md:1).
It answers, repo by repo:
- what was actually read in source
- what value HyperTwist should salvage
- what is subordinate, duplicate, inferior, or off topic
- why that non-promotion decision was made
- which repo should own a domain when two repos overlap
- how the repo should enter `Phase 2R`, `Phase 3R`, or `Phase 6R`
## Storage boundary
To stop future confusion, the storage boundary is now explicit:
- `this packet doc`: source-value extraction, implementation posture, overlap resolution, exclusion rationale
- [REPO_LICENSE_TRACKING.md](C:/HyperTwist/docs/REPO_LICENSE_TRACKING.md:1): repo-row license, attribution, copyright, notice, asset-term, and provenance obligations
- [HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md](C:/HyperTwist/docs/HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md:1): row state and next-step board
- [HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md](C:/HyperTwist/docs/HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md:1): packet sequencing and restart phases
- [HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md](C:/HyperTwist/docs/HYPERTWIST_CANONICAL_RESTART_RECONCILIATION_2026-05-12.md:1): cross-location authority routing
License facts do not belong in this packet unless they affect integration posture.
Deep source-value extraction does not belong in the license tracker.
## Inputs used
This packet was evaluated against:
This rewrite used:
- the current reset board in [HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md](C:/HyperTwist/docs/HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md:1)
- the current reset schedule in [HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md](C:/HyperTwist/docs/HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md:1)
- the current root tracker in [REPO_LICENSE_TRACKING.md](C:/HyperTwist/docs/REPO_LICENSE_TRACKING.md:1)
- the seven source-backed dossier files:
- [18-hactarce-hyperspeedcube-upstream-dossier.md](</C:/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse/18-hactarce-hyperspeedcube-upstream-dossier.md>)
- [19-kkoomen-qbr-upstream-dossier.md](</C:/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse/19-kkoomen-qbr-upstream-dossier.md>)
- [20-vivaansinghvi07-rubix-cube-solver-upstream-dossier.md](</C:/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse/20-vivaansinghvi07-rubix-cube-solver-upstream-dossier.md>)
- [37-aarav2709-kubetimr-upstream-dossier.md](</C:/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse/37-aarav2709-kubetimr-upstream-dossier.md>)
- [15-roice3-magictile-upstream-dossier.md](</C:/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse/15-roice3-magictile-upstream-dossier.md>)
- [16-roice3-magic120cell-upstream-dossier.md](</C:/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse/16-roice3-magic120cell-upstream-dossier.md>)
- [17-roice3-magiccube5d-upstream-dossier.md](</C:/visual_studio_solutions/multi_project/GPT 5.4 HyperTwist parse/17-roice3-magiccube5d-upstream-dossier.md>)
- current reset docs in `C:\HyperTwist\docs`
- current mirrors under `C:\Workspaces\HyperTwist\mirrors\permissive`
- the existing parse-side dossier files for the seven repos
- checked live Unreal surfaces under:
- `C:\HyperTwist\UnrealHyperTwist\Source`
- `C:\HyperTwist\UnrealHyperTwist\Content\HyperTwistTraining\MaterializedCatalog`
## Live-evidence method
## Live-state result
Current live-evidence checks for this packet were run against:
Current live-evidence check result for all seven `0R-A` repos:
- `C:\HyperTwist\UnrealHyperTwist\Source`
- `C:\HyperTwist\UnrealHyperTwist\Content\HyperTwistTraining\MaterializedCatalog`
- no exact live-surface match found in checked Unreal source or materialized catalog
Check method:
That means:
- exact repo-name or common-name string search in checked Unreal source and materialized catalog surfaces
- none of these seven are currently proven live in checked Unreal surfaces
- all seven remain retained candidates, not landed implementation lanes
Result:
## Deep-source evaluation standard from this packet forward
- no exact live-surface match was found for any of the seven `Packet 0R-A` repos
From `0R-A` onward, a repo packet is not complete unless it records:
This means:
- exact source surfaces inspected
- primary value to keep
- secondary value that may be useful later
- explicit non-promotion decisions
- reason for each non-promotion:
- `inferior duplicate`
- `superseded by stronger retained donor`
- `off topic`
- `host-shell glue / legacy packaging`
- `implementation detail better reauthored first-party`
- none of these seven should currently be described as already live in checked Unreal surfaces
- all seven remain retained permissive candidates rather than landed implementation lanes
Future `Phase 0R` packets should follow this same standard.
## Packet-wide hierarchy
This packet does not treat all seven repos as equal.
| Domain | Primary retained owner | Secondary retained owner | Non-promotion rule |
| --- | --- | --- | --- |
| Hyper runtime architecture | `HactarCE/Hyperspeedcube` | `roice3/MagicTile` | `MagicTile`, `Magic120Cell`, and `MagicCube5D` must not displace `Hyperspeedcube` as the runtime-side foundation because the inspected Hyperspeedcube core is more modular and more general. |
| Recognition calibration nucleus | `kkoomen/qbr` | `vivaansinghvi07/rubix-cube-solver` | `rubix-cube-solver` complements `qbr`; it does not replace it because `qbr` is the cleaner calibration and color-normalization anchor. |
| Browser correction / explanation / NxN solve staging | `vivaansinghvi07/rubix-cube-solver` | `kkoomen/qbr` | `qbr` is the capture nucleus, not the explanation shell. |
| Timer / inspection / session stats / splits | `Aarav2709/KubeTimr` | none in `0R-A` | Do not widen it into a general training-platform owner. Keep it as a bounded subsystem donor. |
| Non-Euclidean geometry / topology / macro transport | `roice3/MagicTile` | `roice3/Magic120Cell` | `MagicTile` owns this lane because its inspected geometry/topology and macro remapping logic is broader. |
| Specialized `4D` interaction patterns | `roice3/Magic120Cell` | `roice3/MagicTile` | Use for concrete `120-cell` interaction, visibility, and piece-finding patterns, not as a broader runtime foundation. |
| Specialized `5D` cube-family state / macro UX | `roice3/MagicCube5D` | none in `0R-A` | Keep this repo for `5D` state encoding and macro/progress semantics, not as a general hyper runtime owner. |
## Packet outcome summary
Packet result:
- retained: `7`
- discarded: `0`
- newly proven live: `0`
Resulting retained-set structure:
- primary runtime-side hyper anchor:
- `HactarCE/Hyperspeedcube`
- primary recognition anchor:
- `kkoomen/qbr`
- secondary recognition/reconstruction companion:
- `vivaansinghvi07/rubix-cube-solver`
- focused early subsystem donor:
- `Aarav2709/KubeTimr`
- primary non-Euclidean/topology donor:
- `roice3/MagicTile`
- specialized later hyper donors:
- `roice3/Magic120Cell`
- `roice3/MagicCube5D`
Most important scheduling consequence:
- `Aarav2709/KubeTimr` is the only `Packet 0R-A` repo that currently looks like an early straight permissive subsystem implementation candidate after `Phase 2R`
- the other six remain clearly retained, but they belong to later retained-set architecture and capability-widening waves rather than immediate direct widening
- `Aarav2709/KubeTimr` remains the earliest straight permissive subsystem implementation candidate after `Phase 2R`
- `HactarCE/Hyperspeedcube`, `kkoomen/qbr`, and `roice3/MagicTile` remain architecture-shaping anchors
- `vivaansinghvi07/rubix-cube-solver`, `roice3/Magic120Cell`, and `roice3/MagicCube5D` remain retained but subordinate or specialized
## Packet decisions
| Repo | License | Current live evidence | Phase 0R decision | Implementation lane | Scheduled restart phase |
| --- | --- | --- | --- | --- | --- |
| `HactarCE/Hyperspeedcube` | `MIT` | no exact live-surface match found | retain and ratify as primary runtime-side hypercubing foundation anchor | bounded first-party engine extraction, not product-shell transplant | `Phase 2R` retained-set architecture anchor, then `Phase 6R` simulation/hyper widening lead |
| `kkoomen/qbr` | `MIT` | no exact live-surface match found | retain and ratify as primary live-recognition anchor | bounded permissive CV sidecar/service and calibration/state-reconstruction donor | `Phase 2R` recognition contract anchor, then `Phase 6R` recognition widening lead |
| `vivaansinghvi07/rubix-cube-solver` | `MIT` | no exact live-surface match found | retain as secondary recognition and reconstruction companion behind `qbr` | bounded browser/service contract and explainability companion donor | `Phase 2R` recognition companion design, then `Phase 6R` recognition/browser explanation widening |
| `Aarav2709/KubeTimr` | `MIT` | no exact live-surface match found | retain as focused subsystem donor; do not promote to training-platform owner | straight permissive first-party timer, inspection, split, and session-stat subsystem implementation | `Phase 2R` timer contract freeze, then earliest `Phase 3R` permissive implementation candidate |
| `roice3/MagicTile` | `MIT` | no exact live-surface match found | retain and effectively promote within the hyper donor cluster as top-tier geometry/topology donor | bounded first-party geometry/topology extraction, not runtime-base replacement | `Phase 2R` hyper architecture design anchor, then `Phase 6R` non-Euclidean and topology widening |
| `roice3/Magic120Cell` | `MIT` | no exact live-surface match found | retain as specialized `4D` interaction donor | bounded first-party advanced interaction and visibility extraction | later `Phase 6R` hyper widening after `Hyperspeedcube` and `MagicTile` |
| `roice3/MagicCube5D` | `MIT` | no exact live-surface match found | retain as specialized `5D` cube-family UX donor | bounded first-party advanced cube-family UX and macro/progress extraction | later `Phase 6R` hyper widening after `Hyperspeedcube` and `MagicTile` |
## Repo-by-repo notes
## Repo evaluations
### `HactarCE/Hyperspeedcube`
Source-backed reading:
Inspected source surfaces:
- remains the strongest runtime-side hypercubing foundation in the current retained set
- is already decomposed like a platform, not a thin app shell
- should shape engine-level boundaries, notation/state separation, puzzle definition, and simulation/view-state layering
- [Cargo.toml](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/Cargo.toml:1)
- [crates/hyperpuzzle_core/src/lib.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_core/src/lib.rs:1)
- [crates/hyperpuzzlescript/src/lib.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzlescript/src/lib.rs:1)
- [crates/hypuz_notation/src/lib.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hypuz_notation/src/lib.rs:1)
- [crates/hypershape/src/lib.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hypershape/src/lib.rs:1)
- [crates/hyperpuzzle_impl_symmetric/src/spec.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_impl_symmetric/src/spec.rs:1)
- [crates/hyperpuzzle_impl_symmetric/src/twist_system.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_impl_symmetric/src/twist_system.rs:1)
- [crates/hyperpuzzle_view/src/lib.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_view/src/lib.rs:1)
- [crates/hyperpuzzle_view/src/replay_event.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_view/src/replay_event.rs:1)
- [crates/hyperpuzzle_view/src/simulation/nd_euclid.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_view/src/simulation/nd_euclid.rs:1)
- [crates/hyperpuzzle_view/src/view/nd_euclid.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_view/src/view/nd_euclid.rs:1)
- [crates/hyperpuzzle_log/src/verify.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperpuzzle_log/src/verify.rs:1)
- [crates/hyperstats/src/lib.rs](C:/Workspaces/HyperTwist/mirrors/permissive/HactarCE/Hyperspeedcube/crates/hyperstats/src/lib.rs:1)
Phase `0R` call:
High-value salvage:
- keep
- ratify as the primary runtime-side hyper foundation anchor
- do not treat it as a full product-shell transplant
- the repo is already partitioned like a platform: core puzzle model, puzzle DSL, notation layer, view state, simulation, verification, and stats
- `hyperpuzzle_core` is the strongest current donor for engine boundary design, catalog structure, naming/tagging, scramble constants, and shared puzzle semantics
- `Hyperpuzzlescript` is major value, not trivia: HyperTwist should keep the idea of a first-party puzzle-definition DSL and built-in puzzle package layer
- `hypuz_notation` is a direct donor for notation parsing/serialization families, feature gates, generalized rotations, and transform-aware move grammar
- `hyperpuzzle_impl_symmetric` contributes the strongest current model for symmetric twist systems, constraint handling, factor/product puzzle specs, axis/pole naming, and transform-constrained twisting
- `hypershape` contributes higher-dimensional slicing and shape math
- `hyperpuzzle_view` contributes replay-event taxonomy, drag/twist view-state semantics, transient camera handling, and partial-twist simulation patterns
- `hyperpuzzle_log` contributes solve verification, scramble verification, randomness-beacon posture, and timestamp/trust thinking
- `hyperstats` contributes PB storage and category modeling for speed/FMC/blind style stats
Practical scheduling call:
Subordinate or later value:
- use it in `Phase 2R` to freeze hyper-runtime and simulation boundary decisions
- schedule actual donor realization in `Phase 6R`, not as immediate post-reset widening
- host-shell and packaging crates in the workspace are secondary compared with the domain crates above
- app-level string/resource packaging is real project glue, but it is not where the strategic donor value sits for HyperTwist right now
Non-promotion decisions and rationale:
- do not transplant the whole Rust application shell: `host-shell glue / implementation detail better reauthored first-party`
- do not let `MagicTile`, `Magic120Cell`, or `MagicCube5D` override this repo for runtime-core, notation, or replay schema: `superseded by stronger retained donor`
- do not copy the exact official-build pathing or file-baking arrangement: `implementation detail better reauthored first-party`
Integration call:
- retain as the primary runtime-side hyper foundation anchor
- use it in `Phase 2R` to freeze catalog, DSL, notation, replay, verification, and simulation contracts
- schedule implementation extraction in `Phase 6R`
### `kkoomen/qbr`
Source-backed reading:
Inspected source surfaces:
- remains the best current anchor for live cube recognition, calibration, color normalization, and sticker-grid state extraction
- is narrow but exactly narrow in the right direction
- should define the recognition nucleus, not the whole product shell
- [src/qbr.py](C:/Workspaces/HyperTwist/mirrors/permissive/kkoomen/qbr/src/qbr.py:1)
- [src/video.py](C:/Workspaces/HyperTwist/mirrors/permissive/kkoomen/qbr/src/video.py:1)
- [src/colordetection.py](C:/Workspaces/HyperTwist/mirrors/permissive/kkoomen/qbr/src/colordetection.py:1)
- [src/helpers.py](C:/Workspaces/HyperTwist/mirrors/permissive/kkoomen/qbr/src/helpers.py:1)
- [src/config.py](C:/Workspaces/HyperTwist/mirrors/permissive/kkoomen/qbr/src/config.py:1)
- [src/constants.py](C:/Workspaces/HyperTwist/mirrors/permissive/kkoomen/qbr/src/constants.py:1)
Phase `0R` call:
High-value salvage:
- keep
- ratify as the primary recognition anchor
- keep it ahead of `vivaansinghvi07/rubix-cube-solver`
- persistent per-user cube palette calibration
- dominant-color extraction with `kmeans`
- LAB conversion plus `CIEDE2000` distance matching for perceptual color classification
- contour filtering for square-like stickers
- the center-neighbor heuristic that detects a `3x3` face by finding the contour with nine neighbors including itself
- stable left-to-right, top-to-bottom contour sorting after detection
- preview-state averaging and majority stabilization to reduce flicker and bad reads
- scan completeness validation by enforcing nine occurrences of each color
- BGR-to-notation mapping after normalization
Practical scheduling call:
Subordinate or later value:
- use it in `Phase 2R` to freeze recognition-side contracts, calibration expectations, and CV session seams
- schedule actual donor realization in `Phase 6R`
- direct webcam UI loop, text drawing, and terminal interaction are usable references but not the core donor value
- the direct solve shell around the scanner is secondary to the recognition pipeline itself
Non-promotion decisions and rationale:
- do not promote `qbr.py` as a product-shell donor: `host-shell glue`
- do not treat the direct solver invocation as the main reason to keep the repo: `off topic` to the repo's strongest donor value, which is capture/calibration/state extraction
- do not let `qbr` own the full multi-size explanation/browser lane: `superseded by stronger retained donor` (`vivaansinghvi07/rubix-cube-solver`)
Integration call:
- retain as the primary recognition calibration anchor
- use it in `Phase 2R` to freeze calibration, perceptual color matching, contour ordering, and scan-state contracts
- schedule implementation extraction in `Phase 6R`
### `vivaansinghvi07/rubix-cube-solver`
Source-backed reading:
Inspected source surfaces:
- remains strong enough to stay in the retained set
- is most useful as the bridge between CV-derived state reconstruction, browser-facing correction, websocket flow, and stepwise explanation
- should complement `qbr`, not replace it
- [backend/cv.py](C:/Workspaces/HyperTwist/mirrors/permissive/vivaansinghvi07/rubix-cube-solver/backend/cv.py:1)
- [backend/server.py](C:/Workspaces/HyperTwist/mirrors/permissive/vivaansinghvi07/rubix-cube-solver/backend/server.py:1)
- [backend/test.py](C:/Workspaces/HyperTwist/mirrors/permissive/vivaansinghvi07/rubix-cube-solver/backend/test.py:1)
- [frontend/src/script.js](C:/Workspaces/HyperTwist/mirrors/permissive/vivaansinghvi07/rubix-cube-solver/frontend/src/script.js:1)
Phase `0R` call:
High-value salvage:
- keep
- retain as secondary recognition and reconstruction companion
- do not elevate above `qbr`
- a richer CV reconstruction pipeline than `qbr`, including contour filtering, angle grouping, face grouping, interpolation of missing squares, and explicit invalid-read guardrails
- `ImageToCube` frame accumulation and voting rather than single-frame commitment
- state scoring against a six-state rotation order to stabilize which cube orientation is currently being observed
- support for `2x2`, `3x3`, and larger `NxN` solve staging
- websocket protocol for `init`, `frame`, `finish`, and `solve`
- move normalization and conversion into TwistySim-readable notation, including wide turns, middle-layer conversions, and rear-side layer normalization
- mapping solver pipeline stages to human-readable explanations
- browser-side correction/edit/play flow for validating and correcting inferred state before solve playback
Practical scheduling call:
Subordinate or later value:
- use it in `Phase 2R` for browser correction flow, websocket session contracts, and explanation-flow companion decisions
- schedule actual donor realization in `Phase 6R`
- the exact DOM shell is secondary to the protocol and correction flow
- the exact TwistySim coupling is useful, but HyperTwist should keep the move-normalization contract more than the library tie-in
Non-promotion decisions and rationale:
- do not promote this repo over `qbr` as the primary calibration nucleus: `superseded by stronger retained donor`
- do not promote the browser shell as a direct product-shell donor: `host-shell glue`
- do not treat the exact frontend stack as required: `implementation detail better reauthored first-party`
Integration call:
- retain as the secondary recognition and reconstruction companion behind `qbr`
- use it in `Phase 2R` to freeze browser correction, websocket session flow, frame voting, and explanation contracts
- schedule implementation extraction in `Phase 6R`
### `Aarav2709/KubeTimr`
Source-backed reading:
Inspected source surfaces:
- remains a narrow but clean timer/practice subsystem donor
- is useful for timer-state logic, inspection handling, split capture, rolling session statistics, and local persistence fallbacks
- is too small and too narrow to own the training pillar
- [src/timingEngine.ts](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/timingEngine.ts:1)
- [src/statsEngine.ts](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/statsEngine.ts:1)
- [src/splits.ts](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/splits.ts:1)
- [src/scrambleEngine.ts](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/scrambleEngine.ts:1)
- [src/persistence.ts](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/persistence.ts:1)
- [src/ui/hooks/useTimer.ts](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/ui/hooks/useTimer.ts:1)
- [src/ui/components/VirtualReplay.tsx](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/ui/components/VirtualReplay.tsx:1)
- [src/ui/components/StatsPanel.tsx](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/ui/components/StatsPanel.tsx:1)
- [src/ui/components/SplitEditor.tsx](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/ui/components/SplitEditor.tsx:1)
- [src/ui/components/ScrambleVisualizationModal.tsx](C:/Workspaces/HyperTwist/mirrors/permissive/Aarav2709/KubeTimr/src/ui/components/ScrambleVisualizationModal.tsx:1)
Phase `0R` call:
High-value salvage:
- a clean timer-state machine with inspection, `+2`, and `DNF` handling
- held-to-start control semantics for keyboard and touch
- rolling stats logic for `mo3`, `ao5`, `ao12`, `ao50`, `ao100`, `ao1000`, and `moXAo5`
- per-session PB tracking and chronological timeline construction
- split-phase normalization, ordering validation, capture merging, and per-phase duration calculation
- method presets for `CFOP`, `Roux`, `ZZ`, and `Petrus`
- async scramble prefetching and cache rotation for WCA events
- persistence fallback chain: IndexedDB, then local storage, then memory
- bounded `NxN` scramble visualization logic including wide turns, middle layers, and rotations
Subordinate or later value:
- the UI layout and styling is secondary to the subsystem logic
- the scramble visualization surface is useful, but secondary to the timing/splits/stats model
Non-promotion decisions and rationale:
- do not promote the React UI shell as the main donor: `host-shell glue`
- do not keep the mock replay data generation in `VirtualReplay` as a serious donor surface: `inferior duplicate`
- do not widen `KubeTimr` into a broader training-platform owner: `off topic` relative to the repo's strongest timer/session value
- do not bind HyperTwist permanently to the exact `cubing/scramble` package seam: `implementation detail better reauthored first-party`
Integration call:
- keep
- retain as a focused subsystem donor
- explicitly reject any reading that treats it as already live or as a broader training-platform owner
Practical scheduling call:
- use it in `Phase 2R` to freeze timer, inspection, split, and session-stat contracts
- treat it as the earliest `Packet 0R-A` repo that can likely move into a real `Phase 3R` permissive implementation slice
- use it in `Phase 2R` to freeze timer, inspection, split, stats, and persistence contracts
- treat it as the earliest `0R-A` repo eligible for direct `Phase 3R` permissive implementation
### `roice3/MagicTile`
Source-backed reading:
Inspected source surfaces:
- remains one of the most important geometry/topology donors in the retained set
- is stronger than the stale older CSV posture suggested
- belongs below `Hyperspeedcube` as runtime base, but above generic donor-bench interpretations
- [MagicTile/Puzzle/Puzzle.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/MagicTile/Puzzle/Puzzle.cs:1)
- [MagicTile/Puzzle/Loader.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/MagicTile/Puzzle/Loader.cs:1)
- [MagicTile/Puzzle/State.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/MagicTile/Puzzle/State.cs:1)
- [MagicTile/Puzzle/TopologyAnalyzer.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/MagicTile/Puzzle/TopologyAnalyzer.cs:1)
- [MagicTile/Puzzle/Twisting/TwistHandler.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/MagicTile/Puzzle/Twisting/TwistHandler.cs:1)
- [MagicTile/Puzzle/Twisting/Macro.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/MagicTile/Puzzle/Twisting/Macro.cs:1)
- [R3/R3.Core/Geometry/Tiling.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/R3/R3.Core/Geometry/Tiling.cs:1)
- [R3/R3.Core/Geometry/Polytope.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/R3/R3.Core/Geometry/Polytope.cs:1)
- [R3/R3.Core/Math/Mobius.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/R3/R3.Core/Math/Mobius.cs:1)
- [R3/R3.Core/Math/Matrix4D.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/R3/R3.Core/Math/Matrix4D.cs:1)
- [R3/R3.Core/Honeycombs/H3.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicTile/R3/R3.Core/Honeycombs/H3.cs:1)
Phase `0R` call:
High-value salvage:
- keep
- effectively promote within the hyper donor cluster
- ratify it as the primary non-Euclidean and topology-aware donor
- the strongest current non-Euclidean and topology donor in the packet
- the puzzle builder pattern: tiling generation, master/slave cells, state-calculation cell selection, topology pass, sticker slicing, and twist-data registration
- topology analysis across logical faces, edges, and vertices, including identification merging and Euler characteristic calculation
- state matrix persistence and sticker toggle semantics
- animated twist handling, undo/redo-aware twist history integration, setup-move unwinding, and solve replay behavior
- macro recording and, more importantly, macro remapping through `Mobius` and isometry transforms across reflected or reoriented views
- tiling generation with face/vertex/edge-centered projections and dual-tiling support
- `Mobius` and `Matrix4D` math useful for non-Euclidean interaction and higher-dimensional rotation control
- hyperbolic honeycomb and skew-polyhedron construction patterns that widen HyperTwist beyond ordinary cube families
Practical scheduling call:
Subordinate or later value:
- use it in `Phase 2R` for geometry-family, topology, and non-Euclidean expansion decisions
- schedule actual donor realization in `Phase 6R`
- legacy persistence dialogs and XML log plumbing are useful references, but not the main value
- renderer invalidation and host-specific texture refresh logic are lower-priority implementation detail
Non-promotion decisions and rationale:
- do not promote the WinForms/OpenTK shell as a product-shell donor: `host-shell glue`
- do not promote the exact XML persistence format as a first-party format requirement: `implementation detail better reauthored first-party`
- do not let `MagicTile` replace `Hyperspeedcube` as the runtime-base donor: `superseded by stronger retained donor`
Integration call:
- retain as the primary non-Euclidean, topology, and macro-transport donor
- use it in `Phase 2R` to freeze topology, geometry-family, and transform-aware macro concepts
- schedule implementation extraction in `Phase 6R`
### `roice3/Magic120Cell`
Source-backed reading:
Inspected source surfaces:
- remains worth keeping, but clearly as a specialized later donor
- adds real `4D` visibility, filtering, undo/history, and advanced teaching-surface value
- should stay below `Hyperspeedcube` and `MagicTile`
- [Magic120Cell/cubeFrame.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/Magic120Cell/cubeFrame.cpp:1)
- [Magic120Cell/workFiles/magic120Cell.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/Magic120Cell/workFiles/magic120Cell.cpp:1)
- [Magic120Cell/workFiles/puzzle.h](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/Magic120Cell/workFiles/puzzle.h:1)
- [Magic120Cell/workFiles/cell.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/Magic120Cell/workFiles/cell.cpp:1)
- [geometryLib/puzzle/twist.h](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/geometryLib/puzzle/twist.h:1)
- [geometryLib/puzzle/twistHistory.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/geometryLib/puzzle/twistHistory.cpp:1)
- [geometryLib/puzzle/state.h](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/geometryLib/puzzle/state.h:1)
- [Magic120CellGui/MainFrame.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/Magic120Cell/Magic120CellGui/MainFrame.cs:1)
Phase `0R` call:
High-value salvage:
- explicit `120-cell` visibility families: tori, `4-cube` cells, layers, and rings
- concrete `4D` hypercube overlay and cell grouping logic
- a reusable `CPuzzle` base pattern for settings changes, save/load, highlighting, rotate lifecycle, scramble/reset, solved-state gating, and current-view rotation tracking
- `Cell` rendering and twisting behavior that propagates twist consequences into adjacent cells while also handling per-face fading and logical/physical visibility interactions
- twist encoding around sticker hashes, left/right direction, view rotations, and slice masks
- state models for full-color and antipodal-color puzzle modes
- interaction semantics that are strategically valuable even if the shell is not:
- click sticker to twist cell
- `Ctrl+Click` for `4D` recentering / view rotation
- `Shift+Click` piece highlighting
- `Shift+Ctrl+Click` piece-finding behavior
Subordinate or later value:
- the old WinForms menu shell is secondary to the interaction semantics it exposes
- direct OpenGL host plumbing is lower priority than the puzzle, visibility, and interaction model
Non-promotion decisions and rationale:
- do not promote the WinForms shell as a product donor: `host-shell glue`
- do not promote `Magic120Cell` over `Hyperspeedcube` or `MagicTile` as the primary hyper foundation: `superseded by stronger retained donor`
- do not treat it as the packet's main macro donor: `inferior duplicate` relative to `MagicTile` and `MagicCube5D` for macro-focused value
Integration call:
- keep
- retain as a specialized `4D` interaction donor
- do not promote to foundation status
Practical scheduling call:
- schedule after `Hyperspeedcube` and `MagicTile` in `Phase 6R`
- use it in `Phase 2R` for `4D` view rotation, visibility, piece-finding, and logical-vs-physical display contracts
- schedule implementation extraction later in `Phase 6R`, after `Hyperspeedcube` and `MagicTile`
### `roice3/MagicCube5D`
Source-backed reading:
Inspected source surfaces:
- remains worth keeping as a specialized later donor
- adds real `5D` cube-family UX, macro, progress, slice-control, and teaching-surface value
- should stay below `Hyperspeedcube` and `MagicTile`
- [src/MagicCube5D/workFiles/cube5D.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicCube5D/src/MagicCube5D/workFiles/cube5D.cpp:1)
- [src/MagicCube5D/workFiles/twist.h](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicCube5D/src/MagicCube5D/workFiles/twist.h:1)
- [src/MagicCube5D/workFiles/twist.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicCube5D/src/MagicCube5D/workFiles/twist.cpp:1)
- [src/MagicCube5D/workFiles/stateTransformer.h](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicCube5D/src/MagicCube5D/workFiles/stateTransformer.h:1)
- [src/MagicCube5D/workFiles/stateTransformer.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicCube5D/src/MagicCube5D/workFiles/stateTransformer.cpp:1)
- [src/MagicCube5D/cubeFrame.cpp](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicCube5D/src/MagicCube5D/cubeFrame.cpp:1)
- [src/MagicCubeGui/MainFrame.cs](C:/Workspaces/HyperTwist/mirrors/permissive/roice3/MagicCube5D/src/MagicCubeGui/MainFrame.cs:1)
Phase `0R` call:
High-value salvage:
- keep
- retain as a specialized `5D` cube-family UX donor
- do not promote to foundation status
- compact `5D` state encoding and decoding between sticker arrays and state matrices
- `5D` face-offset and cubie-index mapping logic
- click-twice twist derivation from cubie offsets and axis extraction
- `Ctrl+Click` view rotation semantics around the fifth axis
- macro lifecycle: record, persist, rename, delete, execute forward, execute reverse
- solved-progress tracking beyond binary solved/not solved, including cubie-class statistics
- cubie highlighting by color signatures
- explicit slice-mask semantics for higher-dimensional turns
- projection and stereo-mode controls that reveal how the donor thinks about `5D` inspection and display
Practical scheduling call:
Subordinate or later value:
- schedule after `Hyperspeedcube` and `MagicTile` in `Phase 6R`
- the exact WinForms shell is secondary
- the exact OpenGL stereo/anaglyph implementation is less important than the state, macro, and interaction model
Non-promotion decisions and rationale:
- do not promote the WinForms shell as a product donor: `host-shell glue`
- do not promote the stereo/anaglyph renderer as core packet value: `implementation detail better reauthored first-party`
- do not promote `MagicCube5D` above `Hyperspeedcube` or `MagicTile` as a general hyper runtime donor: `superseded by stronger retained donor`
Integration call:
- retain as a specialized `5D` cube-family UX and state donor
- use it in `Phase 2R` for `5D` state, macro, slice, solved-progress, and click-derived twist contracts
- schedule implementation extraction later in `Phase 6R`, after `Hyperspeedcube` and `MagicTile`
## Net packet interpretation changes
This packet closes several ambiguities:
This rewrite makes the retained-set calls much more precise:
- `Aarav2709/KubeTimr` remains retained, but it is not live and it is not the owner of the broader training architecture
- `HactarCE/Hyperspeedcube` remains the primary hyper runtime anchor
- `kkoomen/qbr` remains the primary recognition anchor
- `vivaansinghvi07/rubix-cube-solver` remains retained as a companion rather than the primary base
- `roice3/MagicTile` deserves stronger retained importance than the older shallow read suggested
- `roice3/Magic120Cell` and `roice3/MagicCube5D` survive, but as later specialized donors rather than early anchors
- `HactarCE/Hyperspeedcube` is not just "important"; it is the inspected primary owner for runtime architecture, DSL, notation, replay semantics, verification, and stats shape
- `kkoomen/qbr` is not just "scanner-ish"; it is the primary calibration and perceptual color-matching nucleus
- `vivaansinghvi07/rubix-cube-solver` is not redundant; it is the retained browser correction, frame-voting, and explanation companion
- `Aarav2709/KubeTimr` is not a platform; it is a high-quality early timer/splits/stats subsystem donor
- `roice3/MagicTile` is not just a later curiosity; it is the main non-Euclidean/topology and macro-transport donor
- `roice3/Magic120Cell` and `roice3/MagicCube5D` stay retained because they add specialized `4D` and `5D` interaction/state value that the packet should not discard, but neither is promoted over the stronger anchors
## Implementation guidance produced by this packet
`Phase 2R` must now create first-party contracts for:
- hyper runtime, DSL, notation, replay, verification, and stats from `Hyperspeedcube`
- recognition calibration from `qbr`
- reconstruction/browser correction/explanation from `rubix-cube-solver`
- timer, inspection, splits, persistence, and stats from `KubeTimr`
- topology, non-Euclidean geometry, and macro transforms from `MagicTile`
- specialized `4D` interaction from `Magic120Cell`
- specialized `5D` state/macro/progress semantics from `MagicCube5D`
`Phase 3R` should start with:
- `Aarav2709/KubeTimr`
`Phase 6R` should widen in this order:
1. `HactarCE/Hyperspeedcube`
2. `kkoomen/qbr`
3. `roice3/MagicTile`
4. `vivaansinghvi07/rubix-cube-solver`
5. `roice3/Magic120Cell`
6. `roice3/MagicCube5D`
## Packet-close result
`Packet 0R-A` is now source-backed, scheduled, and no longer just a placeholder name.
`Packet 0R-A` is now:
It is closed as an evaluation packet.
- source-backed
- overlap-aware
- explicit about what to salvage
- explicit about what not to promote and why
- stored in the correct place for future integration work
The next best clean move is:
It remains closed as an evaluation packet.
1. keep `Packet 0R-A` as the closed anchor packet
2. read `Packet 0R-B` for the now-closed permissive backlog
The next best clean move is to apply this same deep-source standard to the remaining `Phase 0R` packets before any new donor-shaped widening occurs.
3. open `Packet 0R-C` for the remaining non-permissive `Phase 0R` backlog while keeping `Phase 3R+` widening frozen

22
docs/HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md
View file

@ -47,12 +47,27 @@ Packet result:
- discarded: `0`
- newly proven live: `0`
`Packet 0R-A` is no longer just a retain/schedule memo.
It is now the deep-source integration authority for those seven repos and records:
- exact source surfaces inspected
- all promoted value extracted from those surfaces
- every non-promotion decision and the reason for it
- the cross-repo hierarchy for overlapping domains
Most important scheduling result:
- `Aarav2709/KubeTimr` is the earliest `Packet 0R-A` straight permissive subsystem implementation candidate after `Phase 2R`
- `HactarCE/Hyperspeedcube`, `kkoomen/qbr`, and `roice3/MagicTile` are retained-set architecture anchors
- `vivaansinghvi07/rubix-cube-solver`, `roice3/Magic120Cell`, and `roice3/MagicCube5D` remain retained later companions/donors
Mandatory read rule before implementing any `0R-A` repo:
1. read `docs/HYPERTWIST_PHASE_0R_PACKET_0R_A_EVALUATION_2026-05-12.md`
2. read `docs/REPO_LICENSE_TRACKING.md`
3. then apply the phase schedule in this document
## 2026-05-12 Packet 0R-B status
The second `Phase 0R` packet is now also closed as an evaluation packet:
@ -196,6 +211,13 @@ Goal:
- repo-by-repo deep source evaluation for the not-yet-live rows retained after the live-state reset
- after `0R-A` and `0R-B`, `22` rows still remain to be closed
Required method from this point forward:
- read the source directly, not only the ledgers
- extract all meaningful value
- omit only when the surface is an inferior duplicate, superseded by a stronger retained donor, off topic, or host-shell glue with no durable architecture value
- record the rationale every time something is not promoted
Required output for every remaining repo:
- final license posture

6
docs/HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md
View file

@ -32,6 +32,12 @@ That overlay closes evaluation for:
- `roice3/MagicCube5D`
- the remaining `36` permissive candidates closed in `Packet 0R-B`
Important authority correction:
- `Packet 0R-A` is now the deep-source value-extraction and exclusion-rationale authority for its seven repos
- future implementation of those seven repos should start from `Packet 0R-A`, not from this board alone
- this board remains the readable row-state companion, not the place for full source-value extraction
Packet overlay result:
- all `43` non-live permissive rows have now been packet-evaluated