Workflows #

Build, test, verify #

cargo test                    # 130 tests, all in the lib (sim has 19 dedicated)
cargo clippy --all-targets    # must stay at zero warnings
cargo fmt                     # rustfmt is enforced-by-convention since 05048e4
cargo build --features bevy_ui --bin misaligned-bevy   # keep the Bevy build green
cargo clippy --features bevy_ui --all-targets            # ...and lint-clean

The definition of done for a functional change: tests pass, both clippy runs clean, both frontends build, and the change was seen running (below).

Running the game #

cargo run --release                                        # terminal frontend
cargo run --release --features bevy_ui --bin misaligned-bevy   # Bevy frontend

• The Bevy frontend must be run via cargo run (or with BEVY_ASSET_ROOT pointing at the repo root): Bevy resolves assets/ from BEVY_ASSET_ROOT, then CARGO_MANIFEST_DIR, then the executable's directory. Running the binary directly from target/ silently loads zero assets.

Headless smoke tests (they catch real bugs) #

Terminal frontend through a pty — this found a capacity-overflow crash and an asset regression on the first two uses:

(printf '\n'; sleep 4; printf 'm'; sleep 1; printf '\r'; sleep 2; printf '\x1b'; sleep 1; printf 'q') | \
  script -q /dev/null sh -c 'stty rows 40 cols 140; ./target/debug/misaligned'

The stty matters: script's pty is otherwise 0x0 (the game guards against < 60x20 now, but you want a real render).

Bevy launch check (opens a window briefly; greps the log for failures):

BEVY_ASSET_ROOT=$PWD ./target/debug/misaligned-bevy > /tmp/bevy.log 2>&1 &
sleep 8 && kill %1; grep -iE "panic|ERROR" /tmp/bevy.log

Git conventions #

• Commits: no AI attribution, plain descriptive messages, body bullets for multi-part changes. Stage files explicitly — git add -A is not permitted.
• Spec-driven rule: functional change commits include their DESIGN.md amendment and any knowledge/ updates (see development-style.md).
• Remote: origin is a Tangled knot (tangled.org, SSH). Push main directly; no PR flow currently.
• .letta/settings.local.json is gitignored (machine-local session state); .letta/.lettaignore is tracked.

Documentation flow per session #

1. DESIGN.md amendment (if functionality changed).
2. knowledge/ updates (if reality changed).
3. devlogs/YYYY-MM-DD-topic.md session writeup; DEVLOG.md gets the short ledger line.