# HyperTwist Unreal Build Validation Requirement

Date: `2026-06-01`

Status: `active doctrine`

## Purpose

This note makes one operational rule explicit and durable:

If a task changes HyperTwist Unreal C++ code, comprehensive Windows Unreal
build validation is required before the slice is described as landed,
validated, or safe to close.

This rule exists to survive context loss, interrupted sessions, and repeated
phase-ladder work.

## Non-negotiable rule

For HyperTwist Unreal C++ implementation work:

- symbol checks are not enough
- whitespace checks are not enough
- doc-resolution checks are not enough
- local text inspection is not enough

An actual Windows Unreal build must be run for the affected slice unless the
operator explicitly says otherwise.

## Why this is required

Even careful Unreal C++ edits can fail for reasons that text-only review will
not catch, including:

- missing includes
- bad forward declarations
- `UHT` or macro issues
- module dependency mistakes
- signature drift
- generated-code breakage
- linker failures
- config-specific Unreal build failures

Because of that, Unreal C++ work must not be treated as complete based only on
filesystem-level validation.

## Required build target

The canonical Windows build command for this repo is:

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

If the engine path changes later, update this note and the propagated canon
references in the same change.

## Required cadence

Build after each logical Unreal C++ slice or packet.

That means:

- it is acceptable to batch a few tightly related edits that belong to one
  packet and then build once
- it is not acceptable to stack multiple independent Unreal C++ packets and
  defer the build until later
- if a change touches shared headers, reflected types, module boundaries, or
  wide runtime contracts, build immediately after that slice
- doc-only changes do not require a Windows Unreal build

For the current phase-ladder work, the default cadence is:

- one phase
- one Windows Unreal build
- one closeout

## Remote execution posture

When the build is not being run directly on the Windows workstation, use the
documented Windows reachability path rather than silently skipping build
validation.

Current related note:

- `C:\HyperTwist\docs\ops\HYPERTWIST_DEFERRED_TAILSCALE_AND_OPENSSH_LOCAL_REACHABILITY_NOTE_2026-05-31.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_REVERSE_SSH_WINDOWS_BUILD_LANE_VERIFICATION_2026-06-01.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_REVERSE_SSH_AUTH_MODE_MISMATCH_AND_RECOVERY_2026-06-02.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_REVERSE_SSH_LIVE_CONNECTION_FACTS_2026-06-04.md`

That reachability note records the current short-term preference to use reverse
SSH first and defer `Tailscale + OpenSSH` for a calmer setup window.

The current reverse-SSH Windows build lane is not hypothetical; it was
re-verified live on `2026-06-01` through `localhost:22022` on the VPS, and the
fallback lane on `localhost:22023` was exercised on `2026-06-03` after a
stale-listener incident on `22022`.

Operational reading:

- use `localhost:22022` as the primary reverse-SSH lane
- treat that lane as VPS-loopback-only, which means `localhost` is the correct
  bridge target and public `212.227.13.220:22022` is not the expected path
- if `22022` is occupied or accepts TCP but fails SSH banner exchange, treat
  it as stale and shift to `localhost:22023`
- if `22023` is not visibly listening, do not assume fallback availability;
  re-establish it first or report that only the primary lane is currently live
- when recovering from a stale listener, run a split sequence:
  1. smoke login/identity check
  2. canonical Unreal build command with explicit result markers

## Closeout wording requirement

Every Unreal C++ closeout should say one of these explicitly:

- the Windows Unreal build was run successfully
- the Windows Unreal build was run and failed, with the failure described
- the Windows Unreal build was not run, with the reason stated plainly

Do not imply full validation if the Windows build was not run.

## Canonical propagation targets

This requirement must stay aligned with these docs:

- `C:\HyperTwist\AGENTS.md`
- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\AGENTS.md`
- `C:\HyperTwist\docs\v6_5_deep_manual_pack\HyperTwist\ROADMAP.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_IMPLEMENTATION_PHASE_1_KICKOFF.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_DEFERRED_TAILSCALE_AND_OPENSSH_LOCAL_REACHABILITY_NOTE_2026-05-31.md`
- `C:\HyperTwist\docs\ops\HYPERTWIST_REVERSE_SSH_WINDOWS_BUILD_LANE_VERIFICATION_2026-06-01.md`

If this doctrine changes, update those references in the same turn so the rule
does not drop out of working memory again.
