# 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.

Current operational clarification:

- that command remains the canonical repo-root shape for a healthy authoritative
  Windows checkout
- the currently maintained reverse-SSH validation root on the live Windows host
  is `C:\HyperTwist_worktrees\phase10validate`
- `C:\HyperTwist` is currently only a partial mirror on that host and should
  not be assumed to contain a usable authoritative `.uproject` until the live
  host state changes and the reverse-SSH authorities are updated

## 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`.

Additional live proof on `2026-06-11` closed the classic-cube packaged gate over
that same fallback lane: `22022` was refusing SSH, `22023` accepted the
connection, an isolated Windows worktree at
`C:\HyperTwist_worktrees\phase3pkg` was populated from the committed Linux tree,
`Build.bat` succeeded, `BuildCookRun` completed with `ExitCode=0`, archive
output was written to `C:\HyperTwist_worktrees\phase3pkg_packaged`, and the
packaged classic-cube smoke boot succeeded. This means the doctrine now has live
proof not just for editor builds, but for full package/cook/archive/launch
validation over the reverse-SSH lane as well.

Additional live proof on `2026-06-12` closed the dedicated-map and speech or
solver training slice over that same fallback lane: the recovered isolated
Windows worktree `C:\HyperTwist_worktrees\phase3to5` authored
`L_HyperTwist_ClassicTraining`, `L_HyperTwist_FollowAlongTraining`, and the
classic-cube material family, `BuildCookRun` again completed with `ExitCode=0`,
archive output was written to `C:\HyperTwist_worktrees\phase3to5_packaged`, and
packaged smoke boots succeeded on both training maps. This extends the doctrine
from generic packaged proof to dedicated authored-map proof on the same reverse-SSH
lane.

Additional live proof on `2026-06-12` re-established the primary reverse-SSH
lane for the current replay/leaderboard validation packet: both `22022` and
`22023` were visibly listening on the VPS, `22022` accepted the session, the
isolated Windows worktree `C:\HyperTwist_worktrees\phase10validate` passed a
final post-patch `Build.bat` run with UnrealBuildTool `Total execution time:
590.90 seconds`, and the same worktree then passed the full
`HyperTwist.Integration.ClassicCube` suite with
`**** TEST COMPLETE. EXIT CODE: 0 ****`. This extends the doctrine from generic
primary-lane reachability back to current replay/leaderboard integration proof
on the same isolated Windows lane.

Additional live proof on `2026-06-13` closed the current primary-lane package
gate for that same replay/leaderboard source state: the isolated Windows
worktree `C:\HyperTwist_worktrees\phase10validate` required explicit
commandlet/unattended guards in the legacy `UnrealMCP` editor toolbar module
and the maintained `UnrealMCPChong` bridge, after which `BuildCookRun`
completed with `ExitCode=0`, `BuildCookRun time: 164.59 s`, archive output was
written to `C:\HyperTwist_worktrees\phase10validate_packaged`, and packaged
smoke boots succeeded on both `L_HyperTwist_ClassicTraining` and
`L_HyperTwist_FollowAlongTraining`. This extends the doctrine from primary-lane
build-plus-integration proof to primary-lane package/archive/launch proof on
the same current source state.

The maintained helper `scripts\Invoke-HyperTwistClassicCubePackage.ps1` now
defaults its smoke-launch pass across every cooked classic-cube training map in
that package set, so the canonical package-validation path no longer depends on
an operator remembering a second manual packaged boot for follow-along.

That repaired helper path was itself revalidated on `2026-06-13` against
isolated worktree `C:\HyperTwist_worktrees\phase10validate`: archive output was
written to `C:\HyperTwist_worktrees\phase10validate_packaged_repair`,
`BuildCookRun` completed with `ExitCode=0` and `BuildCookRun time: 116.89 s`,
and the helper then smoke-launched both `L_HyperTwist_ClassicTraining` and
`L_HyperTwist_FollowAlongTraining` in its default pass without a manual second
launch step.

Additional live proof on `2026-06-13` also validated the new `Phase 6C`
higher-dimensional activation packet on that same primary lane: the isolated
Windows worktree `C:\HyperTwist_worktrees\phase10validate` invalidated its
editor makefile because the slice added a new translation unit, the resulting
fresh `Build.bat` pass still completed with `Result: Succeeded` and
UnrealBuildTool `Total execution time: 2829.95 seconds`, and targeted
`UnrealEditor-Cmd` automation then found `4` tests under
`HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `4` with
`**** TEST COMPLETE. EXIT CODE: 0 ****`. This extends the doctrine from generic
compile proof to current higher-dimensional activation-catalog proof on the
same primary reverse-SSH lane.

Later `2026-06-13` continuation proof on that same primary lane validated the
active runtime-surface widening above the landed `Phase 6C` packet without
opening a new host/runtime branch: the isolated Windows worktree
`C:\HyperTwist_worktrees\phase10validate` rebuilt the updated runtime-library,
training-panel, and session-actor exposure slice with `Result: Succeeded` and
UnrealBuildTool `Total execution time: 1061.50 seconds`, then targeted
`UnrealEditor-Cmd` automation found `5` tests under
`HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `5`,
including `RunStateActivationResolution`, with
`**** TEST COMPLETE. EXIT CODE: 0 ****`. This extends the doctrine from the
earlier activation-catalog checkpoint into current active-run and
`RuntimeModeId` fallback proof on the same primary reverse-SSH lane.

Further `2026-06-18` continuation proof on that same primary lane recovered an
interrupted follow-up without source corruption: after re-proving the
`localhost:22022` login path and hash-matching the changed subsystem/test files
back into isolated worktree `C:\HyperTwist_worktrees\phase10validate`, the
cleaned-code `Build.bat` pass completed with `Result: Succeeded` and
UnrealBuildTool `Total execution time: 124.81 seconds`, and targeted
`UnrealEditor-Cmd` automation then found `8` tests under
`HyperTwist.FirstParty.HigherDimensional.Phase6C` and passed all `8`,
including `LaunchCatalog`, `ViewContextCatalog`, `LaunchExecution`, and
`RunStateActivationResolution`, with `**** TEST COMPLETE. EXIT CODE: 0 ****`.
The same proof also established that the long quiet `LaunchExecution` interval
can legitimately trigger controller output such as
`Ignoring very large delta of 499.13 seconds` even when the commandlet is
healthy, so that quiet interval is now an expected operational characteristic
of this slice rather than a default corruption signal.

Additional live proof on `2026-06-22` then closed the current maintained
higher-dimensional package-helper lane on that same primary reverse-SSH path:
the isolated Windows worktree `C:\HyperTwist_worktrees\phase10validate`
already had the packaged-game target receipt, so the new helper
`scripts\Invoke-HyperTwistHigherDimensionalPackage.ps1` was validated in
`-SkipBuild` mode against the existing receipt, insisted on manifest-backed
`Magic120Cell` / `MagicCube5D` dedicated-family map hash parity before cook,
completed `BuildCookRun` with `ExitCode=0` and `BuildCookRun time: 118.53 s`,
wrote archive output to
`C:\HyperTwist_worktrees\phase10validate_packaged_phase6c_higherdim`,
smoke-launched both higher-dimensional dedicated-family training maps through
`scripts\Launch-HyperTwistHigherDimensionalPackage.ps1`, and pulled aggregate
proof into
`docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_package_validation_report.json`.
This extends the doctrine from higher-dimensional activation/ownership proof
into current structured package/archive/launch proof on the same primary
reverse-SSH lane.

Further higher-dimensional package-refresh proof on `2026-06-23` then
revalidated that same maintained helper lane after the recovered authoritative
editor rebuild: the isolated Windows worktree
`C:\HyperTwist_worktrees\phase10validate` still had the packaged-game target
receipt, so `scripts\Invoke-HyperTwistHigherDimensionalPackage.ps1` ran again
in `-SkipBuild` mode, completed `BuildCookRun` with `ExitCode=0` and
`BuildCookRun time: 70.74 s`, wrote archive output to
`C:\HyperTwist_worktrees\phase10validate_packaged_phase6c_higherdim_refresh_20260623`,
smoke-launched both higher-dimensional dedicated-family training maps again,
and refreshed the checked-in aggregate proof at
`docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_package_validation_report.json`.
This extends the doctrine from a one-off helper proof into a re-proven
maintained package lane that still stays green after later editor-build
recovery work on the same primary reverse-SSH path.

Further exact-source browser/package refresh proof on `2026-06-30` then
extended that same doctrine into truthful fallback-root recovery when the
maintained isolated Windows worktree was temporarily blocked by host state:
the current primary lane on `localhost:22022` still accepted the session, but
the maintained validation root `C:\HyperTwist_worktrees\phase10validate`
failed its exact-source editor rebuild twice because
`HyperTwistTrainingRepositoryLibrary.cpp` was held by another Windows process.
The new bounded wrapper
`scripts/run-hypertwist-remote-exact-source-browser-package-refresh.sh` then
fell back to isolated root `C:\HTpp`, narrow-synced the exact-source
browser/package support files that that fallback root lacked, rebuilt the
editor there successfully, reran `HyperTwist.Browser` automation with pulled
report `docs/generated/browser_automation/Browser-ExactSource-20260630/index.json`
showing `26` succeeded, `0` failed, `0` not run, and `0` in process, then
performed a truthful full higher-dimensional package build because the fallback
root had no packaged-game target receipt. The refreshed aggregate package
proof still passed, both dedicated-family packaged smoke maps stayed green, and
the checked-in public summary at
`website/src/shared/generated/windows-package-validation-summary.json` was
re-rendered with `skip_build: false`. This extends the doctrine from
maintained-root `-SkipBuild` helper proof into bounded exact-source fallback
proof when a live Windows host lock temporarily makes the maintained root
unusable.

Later same-day maintained-root recovery then tightened the public reading
again: when the exact-source wrapper can once more run a fresh editor build on
`C:\HyperTwist_worktrees\phase10validate` and the maintained package helper
then legitimately reuses the existing packaged-game receipt, the public summary
must present both truths instead of flattening the packet back down to one
`skip_build` boolean. The authoritative package report therefore now carries
both the package-helper `skipBuild` state and the surrounding
`prePackageEditorBuild` result for the same proof packet.

Further XR packaged-validation proof on `2026-07-02` then tightened the same
doctrine again for the native XR lane: the newly added
`scripts\Invoke-HyperTwistXrPackage.ps1` helper first exposed that packaged
artifact existence alone is not sufficient `-SkipBuild` truth, because the
maintained root could still be editor-green while the packaged-game receipt and
Win64 game binary were stale relative to current `.uproject`, `Source`,
`Config`, and `Plugins` inputs. The helper posture was then repaired to require
freshness, after which the same maintained root
`C:\HyperTwist_worktrees\phase10validate` completed a truthful full packaged
rebuild with `Result: Succeeded`, UnrealBuildTool `Total execution time:
2499.70 seconds`, and `BuildCookRun time: 2593.82 s`. The first packaged
windowed smoke then exposed a second real host-context truth by failing
swapchain creation under the unattended reverse-SSH session, so the owned XR
package smoke lane now uses `RuntimeLaunchMode=nullrhi` for structural packaged
launch/ownership proof and reserves `RuntimeLaunchMode=windowed` for future
live headset/controller observation proof. The final exact-source rerun then
stayed green with `BuildCookRun time: 85.47 s`, both XR smoke maps passed, and
checked-in aggregate proof now lives at
`docs/generated/xr/xr_packaged_validation_report_2026-07-02.json`.

Further `2026-06-13` continuation proof on that same primary lane recovered
the classic-cube replay/leaderboard/package slice after a corrupted reverse
sync incident: a prior aborted broad tar sync left remote
`HyperTwistWhisperCppPhase6RESpeechTranscriptContractTest.cpp` damaged inside
`C:\HyperTwist_worktrees\phase10validate`, a targeted hash-matched re-sync
repaired the affected files, the canonical `Build.bat` pass then completed with
`Result: Succeeded` and UnrealBuildTool `Total execution time: 2029.78
seconds`, and fresh `UnrealEditor-Cmd` automation passed all `7`
`HyperTwist.Integration.ClassicCube` tests plus refreshed `Phase 10B`
validation for `Rotation`, `Solve`, `RandomClassicStates`, `Timer.Accuracy`,
and `ClassicCubeMoveParsing`. The same continuation then revalidated the
maintained package helper in `-SkipBuild` mode against the existing packaged
receipt, finishing `BuildCookRun` in `69.16 s`, writing aggregate JSON to
`C:\HyperTwist_worktrees\phase10validate_packaged_phase10b10c9a9c\validation\classic-cube-package-validation-report.json`,
writing per-map smoke JSON beneath `...\validation\smoke\`, and successfully
smoke-booting both classic-cube training maps. This extends the doctrine from
generic package proof into current structured validation-report proof on the
same primary reverse-SSH lane.

Further `2026-06-13` continuation proof on that same primary lane also closed
classic-cube `Phase 9B` Unreal-native media export on isolated worktree
`C:\HyperTwist_worktrees\phase10validate`: `scripts\hypertwist_author_classic_cube_export_assets.py`
successfully authored the authoritative replay-capture `LevelSequence` asset
through `UnrealEditor-Cmd` with `-NullRHI`, then
`scripts\Invoke-HyperTwistClassicCubeMediaExport.ps1` plus
`HyperTwistMoviePipelineReplayExecutor.py` completed the real offscreen
`MovieRenderQueue` render path with canonical MP4, still, share-card, and
aggregate report output under `Saved\MediaExport\ClassicCube\...`. The first
offscreen proof exposed a true timing bug because the authored sequence display
rate was `60 fps` while the export plan and custom end frame were computed at
`30 fps`, which truncated the initial MP4 to `43` frames; aligning the
authored sequence display rate to the export frame rate repaired the final
proof, and post-proof `ffprobe` sanity then confirmed a real `H.264`
`1280x720` / `30 fps` / `85`-frame / `2.8333 s` output. This extends the
doctrine from build/integration/package proof into current headless media-
export proof on the same primary reverse-SSH lane.

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 a short bounded Windows-side PowerShell diagnostic or automation command
  is needed from Linux over the tunnel, prefer
  `scripts/run-hypertwist-remote-windows-powershell.sh` over ad hoc nested
  shell quoting; the wrapper encodes the payload for `powershell -EncodedCommand`
  and was re-proved against the live `22022` lane on `2026-06-23`
- when the next step is a focused `UnrealEditor-Cmd` automation rerun on the
  maintained Windows worktree, prefer
  `scripts/run-hypertwist-remote-unreal-automation.sh`; it composes canonical
  `-NullRHI`, `-ReportExportPath`, `-AbsLog`, and single-filter
  `Automation RunTests ...; Quit` invocations on top of that encoded-
  PowerShell wrapper, and its generated command shape was dry-run-validated on
  `2026-06-23`
- when the next step is a short ordered batch of focused automation reruns on
  that same maintained Windows worktree, prefer
  `scripts/run-hypertwist-remote-unreal-automation-sequence.sh`; it composes
  repeated fail-fast invocations of the single-filter wrapper in the exact
  order provided, and its generated command shape was dry-run-validated on
  `2026-06-23`
- when the next step is the authoritative remote Unreal editor build itself on
  the maintained Windows worktree, prefer
  `scripts/run-hypertwist-remote-unreal-build.sh`; it composes the verified
  `Build.bat` invocation on top of that same encoded-PowerShell wrapper,
  defaults the reverse-SSH lane to the maintained
  `C:\HyperTwist_worktrees\phase10validate` root, and bakes in the
  currently-verified low-memory recovery posture `-NoUBA -MaxParallelActions=2`
  unless explicitly overridden. Its generated command shape was dry-run-
  validated on `2026-06-23`

Canonical helper shape for the next focused post-build reruns:

```bash
HYPERTWIST_REMOTE_WINDOWS_PASSWORD='...' \
scripts/run-hypertwist-remote-unreal-automation.sh \
  --filter HyperTwist.FirstParty.Skill \
  --report-name Skill-Verify

HYPERTWIST_REMOTE_WINDOWS_PASSWORD='...' \
scripts/run-hypertwist-remote-unreal-automation.sh \
  --filter HyperTwist.Permissive.WhisperCpp \
  --report-name WhisperCpp-Verify

HYPERTWIST_REMOTE_WINDOWS_PASSWORD='...' \
scripts/run-hypertwist-remote-unreal-automation-sequence.sh \
  --report-prefix Skill-S3 \
  --filter HyperTwist.FirstParty.Skill.PhaseS3A.ContinuityResumeCoverage \
  --filter HyperTwist.FirstParty.Skill.PhaseS3A.AuthoritativeStoreRead \
  --filter HyperTwist.FirstParty.Skill.PhaseS3A.SerializationRoundTrip
```

- when recovering from a stale listener, run a split sequence:
  1. smoke login/identity check
  2. canonical Unreal build command with explicit result markers
- when an interrupted or superseded `BuildCookRun` leaves stale
  `AutomationTool` / `UnrealBuildTool` `dotnet.exe` processes attached to the
  isolated validation worktree, terminate only those stale toolchain processes
  before rerunning package validation; otherwise the global UBT mutex and
  AutomationTool log files can block a healthy source state from being
  revalidated
- when a broad reverse-sync is interrupted or aborted, do not trust the remote
  validation worktree blindly; hash-check or explicitly re-sync the changed
  files before classifying later compiler failures as a real source regression
- when validating package-helper archive/report behavior and the packaged-game
  receipt already exists, `-SkipBuild` is the preferred proof path over an
  unrelated full game rebuild, but only when the packaged-game receipt and
  binary are both still fresh against current `.uproject`, `Source`, `Config`,
  and `Plugins` inputs rather than merely present
- for reverse-SSH/headless packaged XR proof, a bounded `nullrhi` smoke launch
  is an acceptable structural launch/ownership validation mode, but it does
  not satisfy the separate live headset-session or controller-input observation
  gate
- for the remaining live `windowed` packaged XR observation gate, do not treat
  a reverse-SSH/OpenSSH Session `0` launch as interchangeable with the logged-
  in Windows desktop Session. The current first-party wrapper
  `scripts\Invoke-HyperTwistXrWindowedObservation.ps1` exists specifically so
  that gate can fail fast with preflight evidence when the launcher is not on
  the interactive desktop or when no `OpenXR` active runtime is present
- later same-day `2026-07-02` continuation proof then added
  `scripts\Invoke-HyperTwistInteractiveDesktopTask.ps1`, which lets the
  reverse-SSH Session `0` lane trigger a bounded first-party task inside the
  logged-in Explorer desktop Session `1`; checked-in proof now lives at
  `docs/generated/xr/xr_interactive_desktop_task_probe_2026-07-02.json`
- after that bridge landed, the remaining live packaged XR blocker narrowed
  again: current checked-in rerun
  `docs/generated/xr/xr_windowed_interactive_desktop_probe_2026-07-02.json`
  proves the session-context requirement is satisfied and that the only
  remaining blocker is an absent active `OpenXR` runtime on the Windows
  desktop
- a later same-day continuation then added bounded per-process
  `OpenXrRuntimePathOverride` support to
  `scripts\Launch-HyperTwistXrPackage.ps1` and
  `scripts\Invoke-HyperTwistXrWindowedObservation.ps1`, which let the
  maintained bridge-assisted lane use existing host manifest
  `C:\Windows\System32\MixedRealityRuntime.json` without mutating the machine-
  wide registry
- that same override-backed rerun also exposed a real wrapper defect: the
  packaged runtime report could arrive after the original timeout budget even
  when the packaged runtime itself later reported `result: passed`
- `scripts\Launch-HyperTwistXrPackage.ps1` therefore now carries a bounded
  windowed-only runtime-report grace window, and corrected proof now lives at
  `docs/generated/xr/xr_windowed_interactive_desktop_probe_wmr_override_grace_2026-07-02.json`
- operational reading after that correction:
  - runtime manifest resolution is no longer the remaining live blocker when
    the bounded override seam is used
  - the remaining live blockers are now actual physical headset-session and
    controller-input observation on the Windows desktop
- for reverse-SSH/headless classic-cube replay-export validation, use
  `-NullRHI` only for the asset-authoring leg and `-RenderOffScreen` for the
  actual `MovieRenderQueue` render leg; they solve different failure modes
- when a replay-export end frame is derived from replay duration at a target
  frame rate, keep the authored `LevelSequence` display rate aligned with that
  same frame rate or compute the end frame in sequence-rate units
- when one `UnrealEditor-Cmd` `ExecCmds` string tries to queue multiple
  disjoint `Automation RunTests` filters, inspect the exported report JSON or
  fall back to explicit per-filter invocations; a green exit alone is not
  sufficient proof that every intended filter actually executed
- when an editor-facing plugin still enters `UnrealEditor-Cmd` during cook,
  guard toolbar, Slate, and local bridge startup paths for
  commandlet/unattended execution instead of assuming interactive editor-only
  behavior
- when a higher-dimensional Unreal slice lands first as a first-party
  activation catalog rather than a full interactive renderer, validate both the
  direct contract-resolution tests and the training-run definition bridge on the
  real Windows lane before widening into projection/runtime ownership
- when streaming a Linux-side tar delta into an isolated Windows worktree, use
  `tar -xf ... -m` or explicitly clear the affected generated-header directory
  before building; preserving old mtimes can leave stale
  `Intermediate\Build\Win64\UnrealEditor\Inc\UnrealHyperTwist` outputs in place
  and surface misleading reflected-type or generated-header failures
- when the reverse-SSH Windows lane only has about `1.2 GB` of free physical
  memory and the host still has large resident `chrome.exe` / `Code.exe`
  workloads, expect UnrealBuildTool to serialize down to one active compiler
  worker; treat that as a slow-but-healthy memory-pressure condition rather than
  as tunnel corruption or a looping build unless the compile output itself
  stalls or errors
- when a logical slice authors new `.umap` or `.uasset` authority surfaces in an
  isolated Windows worktree, pull those assets back into the tracked repo before
  calling the slice landed; remote-only authored assets are validation evidence,
  not final repo truth

## Addendum - 2026-06-23 (skill-memory fixture repair and full `S3` proof)

Live follow-up on `2026-06-23` established these additional facts:

- the maintained validation root again stayed
  `C:\HyperTwist_worktrees\phase10validate`
- Windows-side `scp.exe` running on the remote host was re-proved as a safe
  narrow-sync route from the VPS into that isolated worktree for touched
  source files, avoiding a broad reverse-sync just to refresh a few Unreal
  translation units
- after the touched skill-memory source files were hash-matched into that
  worktree, the authoritative incremental editor rebuild succeeded there with
  `Result: Succeeded` and UnrealBuildTool `Total execution time: 104.88
  seconds`
- a fresh focused `S3A` rerun then passed on that rebuilt binary
- the widened same-lane follow-up then produced all `9` expected
  `Skill-S3-Full-PostFixture-*` automation report folders under
  `Saved\AutomationReports`
- each of those `9` report `index.json` files recorded a green result with
  `Succeeded: true`, `SucceededCount: 1`, and `FailedCount: 0`
- that green set covered:
  - `HyperTwist.FirstParty.Skill.PhaseS3A.ContinuityResumeCoverage`
  - `HyperTwist.FirstParty.Skill.PhaseS3A.AuthoritativeStoreRead`
  - `HyperTwist.FirstParty.Skill.PhaseS3A.SerializationRoundTrip`
  - `HyperTwist.FirstParty.Skill.PhaseS3B.RecallCompactViewCoverage`
  - `HyperTwist.FirstParty.Skill.PhaseS3B.AuthoritativeCompactViewLinkage`
  - `HyperTwist.FirstParty.Skill.PhaseS3B.SerializationRoundTrip`
  - `HyperTwist.FirstParty.Skill.PhaseS3C.WorkflowMemoryCaptureCoverage`
  - `HyperTwist.FirstParty.Skill.PhaseS3C.AuthoritativeWorkflowCaptureBoundaries`
  - `HyperTwist.FirstParty.Skill.PhaseS3C.SerializationRoundTrip`

This extends the doctrine from classic-cube, package, higher-dimensional, and
media-export proof into the real remote skill-memory validation lane on the
same maintained reverse-SSH path.

Further live recovery-proof follow-up on `2026-06-23` established:

- a later interrupted remote editor-build attempt had left a stale
  `cmd.exe` / `UnrealBuildTool` tail alive on the maintained validation root
  without active `cl.exe` workers, so the lane was not cleanly post-command
- after terminating only that stale toolchain tail, the same maintained
  validation root `C:\HyperTwist_worktrees\phase10validate` was rerun through
  the canonical helper in the safer single-worker posture
  `scripts/run-hypertwist-remote-unreal-build.sh --max-parallel-actions 1`
- that recovered authoritative rebuild completed with:
  - `Result: Succeeded`
  - `Total time in Parallel executor: 3027.11 seconds`
  - `Total execution time: 3030.86 seconds`
- this recovery materially strengthens the current reading that the earlier
  `fatal error C1060: compiler is out of heap space` result belonged to the
  stale/interrupted or high-pressure lane posture rather than to a stable
  source break in the current HyperTwist tree

## Addendum - 2026-06-29 (exact-source browser proof and refreshed package lane)

Live follow-up on `2026-06-29` established these additional facts:

- the primary reverse-SSH lane on `localhost:22022` remained healthy for the
  current exact-source validation continuation
- the maintained Windows validation root again stayed
  `C:\HyperTwist_worktrees\phase10validate`
- the repo-local wrapper
  `scripts/run-hypertwist-remote-windows-powershell.sh` again proved the live
  Windows identity over that lane before validation by returning:
  - `whoami=desktop-ks3vghu\anthracite ace`
  - `hostname=DESKTOP-KS3VGHU`
- the canonical remote Unreal build helper
  `scripts/run-hypertwist-remote-unreal-build.sh` then revalidated the current
  exact-source editor state with:
  - `Target is up to date`
  - `Result: Succeeded`
  - UnrealBuildTool `Total execution time: 3.40 seconds`
- focused browser automation then reran the full current browser-owned surface
  through:
  `scripts/run-hypertwist-remote-unreal-automation.sh --filter HyperTwist.Browser --report-name Browser-ExactSource-20260629`
  and exported
  `Saved\AutomationReports\Browser-ExactSource-20260629\index.json` with:
  - `26` succeeded
  - `0` failed
  - `0` not run
  - `totalDuration: 12.246334075927734`
- the maintained higher-dimensional package helper was then revalidated again
  on that same exact-source state in `-SkipBuild` mode through
  `scripts\Invoke-HyperTwistHigherDimensionalPackage.ps1`, which:
  - completed `BuildCookRun` with `ExitCode=0`
  - recorded `BuildCookRun time: 64.78 s`
  - wrote archive output to
    `C:\HyperTwist_worktrees\phase10validate_packaged_phase6c_higherdim_refresh_20260629`
  - smoke-launched both dedicated-family maps successfully:
    - `/Game/HyperTwistTraining/Maps/L_HyperTwist_Magic120CellTraining`
    - `/Game/HyperTwistTraining/Maps/L_HyperTwist_MagicCube5DTraining`
  - refreshed the checked-in aggregate report at
    `docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_package_validation_report.json`
- the public/browser release lane was then revalidated against that refreshed
  packaged proof by regenerating
  `website/src/shared/generated/windows-package-validation-summary.json` and
  rerunning `scripts/run-hypertwist-web-surface-validation.sh`, which stayed
  green across:
  - website focused route/auth/release validation: `14` files, `81` tests
  - deployment/readiness tooling validation: `3` files, `30` tests
  - `website/server` validation: `10` files, `36` tests
  - website and `Content/Browser` production builds
  - production audits with the same already-documented upstream
    `supertokens-node -> nodemailer` residual accepted on `website/server`

This extends the doctrine from earlier higher-dimensional package-helper proof
into a refreshed exact-source-state browser plus package plus public-summary
validation packet on the same maintained primary reverse-SSH lane.

## 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.

## Addendum - 2026-06-30 (maintained exact-source recovery closed on the live root)

Later same-day follow-up on `2026-06-30` then closed the maintained-root
recovery on the live primary lane itself rather than only on the temporary
fallback root. The current primary reverse-SSH lane on `localhost:22022`
remained healthy, the maintained Windows validation root stayed
`C:\HyperTwist_worktrees\phase10validate`, and the earlier
`HyperTwistTrainingRepositoryLibrary.cpp` source lock was resolved by stopping
only the stale remote-sync writer trees that still held that file open. After
that host-state repair, the same maintained root exposed two truthful source
parity issues that were then repaired in-bounds: a real local compile seam in
the `Completed` queue-summary branch of
`HyperTwistTrainingRepositoryLibrary.cpp`, and a missing maintained-root copy
of the split coach-repository ownership files
`HyperTwistTrainingRepositoryLibraryCoachWorkflow.cpp` and
`HyperTwistTrainingRepositoryLibraryCoachSummaries.cpp`.

The maintained-lane exact-source wrapper
`scripts/run-hypertwist-remote-exact-source-browser-package-refresh.sh` now
syncs that bounded training-repository ownership set by default alongside the
browser/package support surfaces it already carried, so future maintained-root
exact-source reruns do not depend on ad hoc manual `--sync-file` recovery for
this current family. With that recovery in place, the same maintained root
then completed the full exact-source validation packet cleanly:

- editor build `Result: Succeeded`
- pulled browser report
  `docs/generated/browser_automation/Browser-ExactSource-20260630maintained/index.json`
  with `26` succeeded, `0` failed, `0` not run, and `0` in process
- refreshed higher-dimensional package proof pulled into
  `docs/generated/higher_dimensional_training_maps/phase6c_dedicated_family_package_validation_report.json`
- refreshed public release summary re-rendered into
  `website/src/shared/generated/windows-package-validation-summary.json`
- maintained package archive written to
  `C:\HyperTwist_worktrees\phase10validate_packaged_phase6c_higherdim_refresh_20260630maintained`
- packaged smoke launch succeeded again for both dedicated-family maps:
  `/Game/HyperTwistTraining/Maps/L_HyperTwist_Magic120CellTraining` and
  `/Game/HyperTwistTraining/Maps/L_HyperTwist_MagicCube5DTraining`

This extends the doctrine from fallback-root recovery proof into fully
recovered maintained-root exact-source proof on the same live primary reverse-SSH
lane. The truthful current reading is that `C:\HTpp` remains historical
fallback evidence, while `C:\HyperTwist_worktrees\phase10validate` is again
the latest maintained authority for this browser plus package validation lane.
