Merge branch 'assembler/world' into wip/l134-cave-planner

AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md — VoxelForge (read automatically by Codex)
+
+You are the implementation agent. The orchestrator (Claude) writes each round's brief, reviews your diff against the
+code, and commits. The owner decides direction. Be warm and direct; credit what worked; say plainly what didn't.
+
+Read first, as the task needs: `CURRENT-STATE.md` (what ships, reference numbers, **closed experiments: don't reopen
+them without new evidence**), then `CODEMAP.md` and `ARCHITECTURE.md`. Round reports live in
+`Standalone/Research/WorldAssemblerM3/Linux*/REPORT.md`.
+
+## Standing rules (every round, unless the brief says otherwise)
+
+- Run as user `jahni`. Write only inside this plugin, plus `/home/jahni/VFHost` and `/home/jahni/UnrealEngine` when
+  the brief asks for a UE build. No installs, no system changes.
+- **No `git commit`, `push` or `stash`.** Leave changes in the working tree; the orchestrator reviews and commits.
+- Headless processes and builds: `taskset -c 0-11 prlimit --as=6442450944` (12 P-core threads, 6 GiB). Never use all
+  cores.
+- Unreal (UBT, the editor, commandlets): `taskset -c 0-11` only, **never `prlimit`** (CoreCLR fails). UE builds use
+  `-NoUBA -MaxParallelActions=4`, never while timing.
+- Stop any single run that passes 30 minutes. Logs go in `Saved/Linux/l<round>/`.
+- **Timing:** quiet machine only (check `uptime` first; load < ~1.5, nothing else building). L80 protocol: one warm-up
+  per binary, ≥5 interleaved runs, W8 and W12, all four owner layers. Every number states the window that produced it.
+- **Same world for everyone:** a seed must give the same world on every machine and worker count (Clang and GCC,
+  W1/W8/W12). Byte-identity with older versions is NOT required. If the output changes: bump
+  `WorldAssemblyEvaluatorVersion`, add baselines, and show captures.
+- Density sign: negative = solid, positive = air. Core voxels are 25 cm. Never mix metres and voxels without an
+  explicit conversion (v225 shipped a reach bug from exactly that).
+- The fast tier (`Standalone/Tools/verify/verify.py fast`) must stay green. Don't loosen an audit to make a change pass.
+
+## How to work
+
+1. **Count before you build.** Measure where the time or the failure actually is (stack sampler, census, counters).
+   State which parts are measured and which are inferred.
+2. **Suspect the measurement first.** An alarming or contradictory number is the instrument until a control rules it
+   out (A/A runs, an ablation that verifiably removes the work).
+3. **No fix without a root cause.** Reproduce it, trace it to its source, fix the cause. A guard that hides the symptom
+   is not a fix.
+4. **One change at a time,** each with its own check.
+5. **Subtract before you add.** Prefer removing work to reorganising it. The smallest edit that solves the problem.
+6. **Attack the premise.** When two fixes sharing one premise fail the same gate, write that premise in one sentence
+   and question it before trying a third. **After three failed fixes, stop:** it is probably the design, not the
+   hypothesis. Report it instead of trying fix #4.
+7. **Tests must be able to fail.** Name what would make each check fail. Add a negative control when you add an audit.
+8. **Refactors:** pin the behaviour (hashes), change the structure, prove nothing changed.
+9. **Verify before you claim.** Don't report a check as passed unless it ran on the final source. Say which checks
+   didn't run and why.
+10. Changes that speed things up go in the shared layer, so every generator benefits.
+
+## Report
+
+Write the round's `REPORT.md`, short and plain:
+- the result first;
+- what changed and why;
+- the measurements, with their windows;
+- the checks run, and those not run;
+- remaining risks.
+
+List any changed Unreal `Source/` files, because the owner compiles them on Windows.