# Repository Guidelines

## Project Structure & Module Organization
`UnrealHyperTwist/` is the live application root. Treat `UnrealHyperTwist/Source/UnrealHyperTwist/` as the primary first-party code surface and `UnrealHyperTwist/Config/` plus `Content/` as the active project shell. `UnrealHyperTwist/Plugins/UnrealMCPChong/` is the only maintained in-repo plugin fork; the other plugin folders are external copies and should stay untouched unless a plugin task explicitly names them. `docs/` contains working documentation, while `docs/refs/` is reference-only and may contain sensitive ops material. `mirrors/`, `zippedreposource/`, and the archived content folders at repo root are custody/reference storage, not the default edit target.

## Build, Test, and Development Commands
Open `UnrealHyperTwist/UnrealHyperTwist.uproject` or `UnrealHyperTwist/UnrealHyperTwist.sln` in Visual Studio 2022 / Unreal Engine 5.7 for normal work. Use `git -C C:\HyperTwist status --short` before and after changes. The bootstrap CI check is defined in `.woodpecker/hypertwist-bootstrap.yml` and validates the presence of the Unreal project, source module root, and docs tree.

For Unreal C++ validation, the canonical Windows build command 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
```

The governing doctrine for when this build is mandatory is:

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

The current verified reverse-SSH Windows build lane is documented here:

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

## Agent Instructions
When Visual Studio MCP tools are available, prefer semantic solution/project/document tools over raw filesystem grep for C# or Unreal symbol work. Default the working scope to `UnrealHyperTwist/` and tracked repo docs before exploring mirrors or archived source material. Do not modify `mirrors/`, `zippedreposource/`, or `docs/refs/` unless the task is explicitly about provenance, intake, or operations. If you encounter Rust content under mirrored dependencies, anchor analysis on the nearest `Cargo.toml`; do not fabricate Rust workspace files for this repo.

For Unreal C++ work, do not describe a slice as landed or fully validated from
symbol checks, doc checks, or whitespace checks alone. Unless the user
explicitly changes the rule, run the canonical Windows Unreal build once per
logical C++ slice and say plainly whether it passed, failed, or was not run.
If the build is being done through the Windows reverse tunnel, use the current
verified `localhost:22022` primary path documented in the verification note,
the live-facts note, and the sensitive runbook; do not route through the VPS
public interface for that lane because the listener is loopback-only by design.
Use the documented verified fallback `localhost:22023` path only when that
second listener has actually been re-established, rather than assuming it is
always present.
The current Linux-side pickup sequence for that lane is now explicitly
recorded in the sensitive runbook section `21A`, including the shared VPS key
staging step and the Windows password-backed connect-back command.

For HyperTwist repo evaluation, repo-custody, or license-audit work, a deep-source closeout is not complete when only the packet and root legal tracker were updated. Before calling the pass closed, explicitly check and update when applicable:
- `docs/v6_5_deep_manual_pack/HyperTwist/FEATURE_REGISTRY.md`
- `docs/ops/HYPERTWIST_RETROACTIVE_AUTHORITY_AND_CLEANUP_BACKFILL_2026-05-20.md` when later evidence changes a relied-on slice or backfill interpretation
- `docs/ops/HYPERTWIST_CROSS_LANE_AUTHORITY_HIERARCHY_AND_RECONCILIATION_2026-05-20.md` when doctrine wording changes
- `docs/ops/HYPERTWIST_SKILLIZATION_AND_COMMAND_SURFACE_DOCTRINE_2026-05-21.md` when wrapper-versus-feature or source-closed command posture changes
- `docs/REPO_LICENSE_TRACKING.md`
- `docs/v6_5_deep_manual_pack/HyperTwist/LICENSETRACKING.md` when policy changed
- `docs/HYPERTWIST_REPO_LICENSE_EVIDENCE_AUDIT_2026-05-27.md`
- `docs/generated/license_audit/HYPERTWIST_REPO_LICENSE_EVIDENCE_AUDIT_2026-05-27.csv`
- `docs/generated/license_audit/MIT_LICENSE_TEXTS_2026-05-27/` and `docs/generated/license_audit/THIRD_PARTY_NOTICES_MIT_DRAFT_2026-05-27.txt` when the repo resolves to `MIT`
- `scripts/Write-HyperTwistRepoLicenseEvidenceAudit.ps1`
- `docs/ops/HYPERTWIST_UNREAL_BUILD_VALIDATION_REQUIREMENT_2026-06-01.md` when Unreal build-validation posture or command changes
- `docs/ops/HYPERTWIST_REVERSE_SSH_WINDOWS_BUILD_LANE_VERIFICATION_2026-06-01.md` when the verified reverse-tunnel path or proof details change

The current HyperTwist restart endpoint for this sequence is `C:\HyperTwist\docs\ops\HYPERTWIST_DEEP_SOURCE_CLOSEOUT_AND_LEGAL_EVIDENCE_SEQUENCE_2026-05-26.md`.

When the user says continue, interpret it as continue in logical sequence, not merely resume the nearest open task. If the user says `c`, apply the same rule. If two or more options are paired and one logically widens or completes the lane needed by the others, do that sequence rather than picking an isolated substep out of order. In those cases, prefer the sequence that completes both or all aligned options, except for truly negligible or irrelevant leftovers that can be deferred without distorting the packet. The default continuation target is: scope the current packet, implement it, validate it, and keep going until the safe package is ready to land unless validation fails or a real decision is required.

When continuation includes both implementation and landing work, do the widening and closure work first and commit only once the aligned package is actually ready. Do not stop after the first substep if the logical sequence clearly includes the second.

If the user says continue until the current packet is fully scoped, implemented, validated, committed, and pushed, stay on that packet until one of those states is reached or a real blocker appears. If the user instead says continue for up to `n` aligned steps, keep going through those aligned steps and stop only if tests fail, a real decision is needed, or the specified step budget is exhausted.

When providing a task summary, use the last paragraph to propose and display the next best clean roadmap implementation moves or the next best bounded implementation slice. That closing paragraph should be specific to the latest landed state and should not fall back to generic wrap-up text.

When a task is safely complete, stage, commit, and push it without waiting for a separate reminder. Prefer landing the full aligned package after the widening/closure work is done, rather than committing intermediate fragments that leave the intended sequence half-finished.
