# HyperTwist - DEVELOPMENT.md

## Development philosophy

HyperTwist should be developed as a serious native product:

- Unreal project as the main runtime
- C++ simulation, training, and recognition core
- bounded sidecars where they materially help
- minimal web-only surface

## Canonical development authorities

Use these before widening implementation:

- `ROADMAP.md` for current queue truth
- `FEATURE_REGISTRY.md` for normalized feature truth
- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md` for
  current landed runtime anchors
- `C:\HyperTwist\docs\HYPERTWIST_MODEL_A_MODEL_B_COORDINATOR_DOCTRINE_2026-05-14.md`
  for implementation-state discipline
- `C:\HyperTwist\docs\ops\HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md`
  for `A/R/F` authority resolution

## Current development gate

Do not reopen broad donor-driven widening as if the whole retained portfolio
were already settled.

State-separation rule:

- bookmarked = intake only
- queued = sequencing only
- source-read = evidence gained
- retained = survives evaluation in some posture
- product-fit = separate judgment
- implementation-authorized = explicitly approved bounded build work
- implemented = actually landed in first-party product surfaces

Do not let bookmark presence, queue position, or docs metadata masquerade as
product intent or proof of implementation.

## Donor-strength rule

- donor strength and legal posture are separate axes
- a restrictive or boundary-sensitive repo can still be the strongest owner
  for a lane
- route difficulty changes how retained value may enter the product, not
  whether it may win technically

## Current live implementation truth

Do not use this file as the canonical count surface.

For the current exact implemented-row counts, landed packets, and queue head,
use:

- `ROADMAP.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md`

## Memory / provider / skillization correction

Future widening should now follow explicit doctrine rather than generic prose:

- memory:
  `C:\HyperTwist\docs\ops\HYPERTWIST_MEMORY_LANE_AUTHORITY_AND_PHASE_IMPLEMENTATION_DOCTRINE_2026-05-21.md`
- provider/BYOK:
  `C:\HyperTwist\docs\ops\HYPERTWIST_PROVIDER_NEUTRALITY_AND_BYOK_DOCTRINE_2026-05-21.md`
- skillization/command surface:
  `C:\HyperTwist\docs\ops\HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md`

## Model A interpretation rule

For boundary-sensitive and restrictive rows:

- future `Model A` work should still pursue full bounded realization of the
  retained domain
- `do not promote` and similar wording in `0R` packets is a boundary filter,
  not a cap on later source-value extraction depth
- if a retained handoff is too thin, strengthen the packet/scrubbed handoff
  while preserving no-copy guardrails

## Suggested product module families

- `Source/UnrealHyperTwist/Core`
- `Source/UnrealHyperTwist/Simulation`
- `Source/UnrealHyperTwist/Recognition`
- `Source/UnrealHyperTwist/Replay`
- `Source/UnrealHyperTwist/Training`
- `Source/UnrealHyperTwist/Coach`
- `Source/UnrealHyperTwist/XR`
- later bounded memory/provider/skill families where justified

## Build order

1. preserve and document landed implementation truth
2. respect retained-set routing and packet authority
3. widen through bounded permissive, boundary-sensitive, or clean-room packets
   only
4. keep current queue truth in `ROADMAP.md`
5. route future memory/provider/skill work through their governing doctrines

## Testing

- move/state correctness
- replay integrity
- reconstruction/recognition uncertainty handling
- coaching recommendation stability
- topology/runtime validation
- progression persistence and analytics
