# Workflows

```
Type: knowledge
```
## Build, test, verify

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

```bash
./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:

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
(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):

```bash
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:

  ```bash
  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:

  ```bash
  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.