# HyperTwist — AGENTS.md

## What HyperTwist is

HyperTwist is the portfolio’s cube and hypercube training environment. It must preserve two identities at once:
- a practical physical-cube recognition, replay, and coaching platform
- a serious higher-dimensional simulation and hypercubing environment

It is not enough for HyperTwist to be good at only one of those.

## Authority order

1. `repo_portfolio_unified_v6_3.*`
2. `C:\HyperTwist\docs\HT_REPO_INCORPORATION_AUDIT_2026-05-11.md`
3. `C:\HyperTwist\docs\HYPERTWIST_REPO_EVALUATION_RESET_AND_IMPLEMENTATION_SCHEDULE_2026-05-11.md`
4. `C:\HyperTwist\docs\HYPERTWIST_REPO_STATE_BOARD_2026-05-11.md`
5. This `AGENTS.md`
6. The rest of the HyperTwist v6.5 manual set
7. CubeForge initial research as **inspiration only**, not as code to directly integrate

## Core directives

### Dual-pillar preservation
Never collapse:
- physical cube pipeline
- hypercube simulation pipeline

They are parallel pillars that reinforce each other.

### Unreal-first posture
HyperTwist is native-first. The main runtime should be Unreal Engine 5.4+ with:
- C++ core systems
- Blueprints for UX and training orchestration
- optional OpenXR/VR/MR modes where they materially strengthen higher-dimensional learning

### Unreal build-validation posture
For Unreal C++ work, comprehensive Windows Unreal build validation is
mandatory before a slice is described as landed or fully validated.

Canonical doctrine doc:

- `C:\HyperTwist\docs\ops\HYPERTWIST_UNREAL_BUILD_VALIDATION_REQUIREMENT_2026-06-01.md`

Current verified reverse-SSH Windows build-lane proof:

- `C:\HyperTwist\docs\ops\HYPERTWIST_REVERSE_SSH_WINDOWS_BUILD_LANE_VERIFICATION_2026-06-01.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_REVERSE_SSH_LIVE_CONNECTION_FACTS_2026-06-04.md`

Canonical build command:

```powershell
"C:\Program Files\Epic Games\UE_5.7\Engine\Build\BatchFiles\Build.bat" UnrealHyperTwistEditor Win64 Development C:\HyperTwist\UnrealHyperTwist\UnrealHyperTwist.uproject -WaitMutex -NoHotReloadFromIDE
```

Default cadence:

- one logical Unreal C++ slice
- one Windows Unreal build
- one closeout

Text-only validation is not a substitute for that build.

If the build is being run from a VPS-side AI session, the currently verified
connect-back lane is the reverse-SSH primary path on `localhost:22022`, with
the documented verified fallback path on `localhost:22023` only when that
listener has been explicitly re-established and verified alive.
Treat the lane as loopback-only on the VPS side, which means the correct
bridge target is `localhost` rather than the VPS public interface.
The current Linux-side pickup sequence for that lane is explicitly recorded in
the sensitive runbook section `21A`, including the shared VPS key staging step
and the Windows password-backed connect-back command.

### Backbone language bias
Prefer:
- C++
- Rust
- bounded C#

Minimize:
- TypeScript
- Node.js
- Python

But do not remove them where they are still the best practical host for:
- CV/model inference
- certain training or ingestion helpers
- thin companion UIs

## Repo classification lens

HyperTwist repos should be judged in these families:
- hypercube simulation foundations
- 3D twisty-puzzle foundations
- physical-cube recognition
- replay and solve analytics
- training and curriculum
- coaching and personalization
- immersive rendering / XR
- export and progression

## Coding-model duties

For any HyperTwist repo, the coding model must determine:
- what is truly implemented
- whether it strengthens the physical pipeline, the hyper pipeline, or both
- whether it belongs natively in the runtime, in a sidecar, or only as donor logic
- whether it should be treated as foundation, strategic donor, reserve, or comparator
- whether additional org/index harvesting is still worthwhile

## Model A extraction doctrine

For future `Model A` source-reading work:
- maximize retained value inside the approved lane
- treat `do not promote`, `do not preserve literally`, and similar wording as boundary protection, not as a shallow-extraction rule
- exclude only inferior duplicate value, off-topic value, host-shell glue, commodity scaffolding, literal carryover, or ownership-displacing value
- if an existing handoff undercaptures retained value, strengthen the handoff rather than pushing ambiguity into later clean-room implementation

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

## Current implementation truth

For HyperTwist, keep this explicit:

- current shallow-eval set: `75` repos
- currently verified live/implemented in checked Unreal surfaces: `33`
- permissive live lanes: `21`
- boundary-sensitive live lanes: `7`
- restrictive live lanes: `5`
- current repo-row source-truth pack therefore sits at `33` live rows
  overall: `21` permissive, `7` boundary-sensitive, and `5` restrictive
  clean-room lanes
- within that `75`-row shallow-eval set, the later landed permissive preserve
  rows now also include `HactarCE/Hyperspeedcube`, `kkoomen/qbr`,
  `vivaansinghvi07/rubix-cube-solver`, `roice3/MagicTile`,
  `roice3/Magic120Cell`, and `roice3/MagicCube5D`
- the restrictive landed lanes are `onionhoney/roux-trainers`,
  `cubing/alg.js`, `cubing/twisty.js`, `HactarCE/2x2x2x2-Scrambler`, and
  `kash/cubedesk`, and they are to be treated as properly clean-roomed and
  then implemented

Do not collapse:

- `selected`
- `locked strategic donor`
- `integrate`
- `repurpose`

into:

- `already implemented`

## Reset rule

Before recommending new HyperTwist donor-shaped widening from the remaining
`42` current non-live rows:

- do not reopen the already closed `Phase 0R`, `Phase 1R`, or `Phase 2R` packets
- preserve the twenty-nine landed rows as current truth
- continue from the closed packet sequence with no default new `Phase 5R-A`
  opening; use the landed restrictive per-lane authority for
  `onionhoney/roux-trainers`, `cubing/alg.js`, `cubing/twisty.js`,
  `HactarCE/2x2x2x2-Scrambler`, and `kash/cubedesk`, and keep the optional
  `Phase 3R-G` comparison lane deferred unless the landed primary browser
  spatial stack exposes a real gap
