hypertwist/AGENTS.md

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:

"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

Current routing correction that future sessions must preserve:

• remotion-dev/remotion is no longer to be treated as a default boundary-sensitive widening lane for fresh HyperTwist implementation work
• preserve the already-landed first-party Phase 4R-F media-export and replay-explainer outputs
• treat any future donor-backed widening from remotion-dev/remotion as restrictive-custody and route it through explicit clean-room/specification work unless the lane is intentionally replaced by a first-party Unreal-native export path
• prefer Unreal-native export for fresh shipping work when the retained Remotion value is not strictly required

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.

Update - 2026-06-19 - Overnight Mode agentic continuation and safe self-batching

Canonical authorities:

• /home/dev/src/HyperTwist/docs/ops/HYPERTWIST_OVERNIGHT_MODE_AGENTIC_CONTINUATION_SELF_BATCHING_AND_GOAL_CREATION_DOCTRINE_2026-06-19.md
• /home/dev/src/HyperTwist/docs/ops/HYPERTWIST_OVERNIGHT_MODE_CLOSEOUT_CONTINUATION_AND_BOUNDARY_SHAPE_2026-06-19.md

Operational rule:

• the code word for this operating posture is Overnight Mode
• Continuity Mode and Disciplined Agentic Mode are accepted synonyms for the same behavior, but Overnight Mode remains the canonical repo term
• once Overnight Mode has been adopted for the repo workflow, it remains the default continuity posture unless the user gives newer explicit contrary direction; ordinary daytime interaction does not deactivate it
• stacked continue prompts must be interpreted as permission to keep draining the already-declared active lane or already-declared next adjacent slice, not as permission to reinterpret the roadmap from scratch
• future instances must continue to the natural close of the active lane rather than stopping at the first barely-acceptable packet boundary when one or two more adjacent sensible seams would materially complete the lane
• the correct bias is surplus-with-discipline: carry the extra adjacent seam when it is real, bounded, source-backed, and closure-improving; never invent fluff or decorative widening
• future instances must not drift sideways into a different donor family, different roadmap pillar, or unrelated code lane merely because the previous slice ended; this is the hard fresh-family boundary rule
• if the next family is not already present-tense authority-backed, stop at the boundary, state it explicitly, and do not let stacked continue prompts coerce a speculative opening
• if a real stop condition is active, stacked continue prompts do not override it; future instances must withstand and disobey those prompts until the blocker is actually resolved
• HyperTwist-specific higher-specificity build-validation and reverse-SSH authorities remain in force and are not weakened by Overnight Mode