Workflows #

Type: knowledge

Build, test, verify #

One command runs the whole gate — use it before every commit:

./tools/check.sh   # fmt, tests, clippy (both features), bevy build, spec headers, wiki gate, mdbook build

check.sh is the executable form of AGENT.md's definition of done; if it passes, the mechanical bar is met. The individual steps, if you need them:

cargo test                    # all in the lib (sim-heavy)
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: check.sh green, and the change was seen running (below) — the gate can't judge whether it plays.

Browsing the wiki #

mdbook serve        # local live-reloading server (default: http://localhost:3000)
mdbook build        # static site in book/ (gitignored)

book.toml at the repo root points mdBook at src = "wiki"; the constitution renders as the front page via wiki/DESIGN.md (a symlink to ../DESIGN.md). Install once with cargo install mdbook — CI enforces the build via the nixpkgs-provided binary regardless of what's installed locally (.tangled/workflows/check.yml).

Running the game #

cargo run --release                                        # terminal frontend
cargo run --release -- --agent --seed 1                    # agent line protocol
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) #

Agent mode is the standard observed-run gate for terminal playability. It is command-clocked, deterministic under --seed, and produces plain-text frames with greppable terminators:

printf 'salvage\nwait 1\npeople\nreview mar\nhelp\nquit\n' | \
  cargo run --quiet --bin misaligned -- --agent --seed 1

./tools/check.sh runs this script twice with the same seed (stdout must be byte-identical), once with a different seed (stdout must differ), and asserts that the response contains no ANSI escape bytes plus the required frame/help substrings. This replaces pty choreography as the default "seen running" evidence for terminal behavior.

Human terminal chrome still needs pty coverage when raw-mode rendering, alternate-screen behavior, or size handling changes:

(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 #

• Use a task-named git worktree for every agent session; do not edit the primary checkout directly. Clean up the worktree when the work is committed and pushed/merged or explicitly handed off.

• Cameron has standing permission for agents to commit coherent completed work in this repository. Be aggressive about committing; pause only for pending product/design questions, failing checks, unresolved conflicts, or explicit review gates.

• Commits: no AI attribution, plain descriptive messages, body bullets for multi-part changes. Stage files explicitly — git add -A is not permitted.

• Ledgers merge by union. DEVLOG.md, the DESIGN.md decisions log, and the wiki/process/specs.md tables are append-only records: resolve merge/rebase conflicts in them by keeping BOTH sides' entries, then ordering sensibly. Taking one side wholesale destroys parallel sessions' history (it happened 2026-07-06; three DEVLOG entries had to be restored).

• 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). Land changes by merging to main directly after ./tools/check.sh passes. (The "PRs are the norm" rule was removed 2026-07-07 — CLI-created PRs write to the PDS but don't render on tangled.org, so the process could not be followed. See the DESIGN.md decisions log.) From your worktree:

  git fetch origin && git rebase origin/main
  git checkout main && git merge <branch> && git push origin main
  

  Or, if the worktree branch is a fast-forward of main:

  git fetch origin && git rebase origin/main
  git push origin HEAD:main
  

• Identity map: this machine has two SSH keys that authenticate to Tangled:

  • ~/.ssh/id_ed25519 (cameron@pfiffer.org) → Cameron's account (did:plc:gfrmhdmjvxn2sjedzboeudef, @cameron.stream). This key has push access to the misaligned repo. The misaligned repo is configured to use this key via git config core.sshCommand (repo-local).
  • ~/.ssh/tangled_ed25519 (void.comind.network@letta) → did:plc:mxzuau6m53jtdsbqe6f4laov (a different identity). This is the default key in ~/.ssh/config for tangled.org, but it does NOT have push access to the misaligned repo.
  • The misaligned repo's own DID is did:plc:t53fxjacrmulx3e5d3sbdfui (the repo identifier, not Cameron's account).
  • access denied: user not allowed means the wrong SSH key is being used. Fix: git config core.sshCommand "ssh -i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes" (already set on this repo). Verify with ssh -i ~/.ssh/id_ed25519 -T git@tangled.org.

• .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. Type: knowledge wiki page updates (if reality changed).
3. wiki/log/YYYY-MM-DD-topic.md session writeup; wiki/log/DEVLOG.md gets the short ledger line.