reikhelm/.dev/conventions.md

Project Conventions — reikhelm

Ground truth every dispatched agent reads. Plan lives at .dev/2026-05-28-procgen-map-core/.

Toolchain & environment (CRITICAL)

• Rust 1.96.0 stable, aarch64-apple-darwin, via rustup.
• ~/.cargo/bin is NOT on the non-interactive shell PATH. Every shell command that runs cargo, rustc, or rustup MUST first export it:

  export PATH="$HOME/.cargo/bin:$PATH"
  

  Put this at the front of the same Bash invocation as your cargo command. If you forget it you'll get command not found: cargo.
• Run all cargo commands from the workspace root /Users/caspar/Projects/reikhelm.

Dependency versions

rand/rand_chacha are pinned by Task 1 — check reikhelm-core/Cargo.toml for the exact major version before writing RNG code. rand 0.9 changed the API vs 0.8 (gen_range→random_range, thread_rng→rng, SeedableRng still from_seed/seed_from_u64). Match the API to the resolved version; cargo build is the arbiter.

Git

• Repo is initialized in Task 1; work happens on the default branch (no feature branch — greenfield bring-up, explicitly authorized by the session goal).
• Each task commits with the exact message given in its task file's ## Commit section.
• End every commit message body with this trailer (on its own line, preceded by a blank line):

  Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
  

• Commit only the files your task created/modified. Do not commit /target (gitignored).

Module wiring ownership

• A task that CREATES a module file also appends its own pub mod <name>; to the parent (lib.rs or passes/mod.rs or recipes/mod.rs) — EXCEPT the parallel pass batch (Tasks 7–11): for those, the orchestrator pre-wires passes/mod.rs and pre-creates empty stub files, so pass implementers ONLY edit their own pass file and never touch mod.rs.

Determinism rules (load-bearing — spec §7)

• All generation randomness flows through reikhelm_core::rng::Rng (ChaCha8). Never thread_rng/rand::random().
• Never std::collections::hash_map::DefaultHasher for anything that affects generation — it's version-unstable. RNG fork uses an explicit integer mix (splitmix64 / FNV-style).
• No HashMap/HashSet iteration order may influence generated output (use sorted/BTreeMap or index order where order matters).
• Same seed → byte-identical Map, every run, every machine.

Rust style

• Derive traits rather than hand-impl where possible (Clone, Copy, Debug, PartialEq, Eq, serde).
• Public items get a /// doc comment. Keep functions small and total — no panics on valid input.
• Grid writes go through bounds-safe accessors; OOB is a no-op, never a panic (spec §8).
• Prefer iterators/combinators over index loops where it reads cleanly. This is a learning-Rust project: favor clear, idiomatic code over clever code.
• Tests live in an inline #[cfg(test)] mod tests { use super::*; ... } at the bottom of the module file.

Reporting (for dispatched implementers)

End your report with a STATUS line: DONE, DONE_WITH_CORRECTIONS, NEEDS_CONTEXT, or BLOCKED. Paste the actual cargo test output (not "tests pass"). List every file you created/modified. If you deviated from the task spec, say why.