# Working in this repository

Standing rules for any agent here, including a lane in its own worktree.

## Never

- **Touch anything under `/home/joe/Development/fnm/`.** The author's live
  working copy, with an editor session attached. This repository's `sand.flan`
  is a different file and may be edited normally.
- **Execute `examples/*.flan`, `sand.flan`, or anything linking raylib.** They
  open a window that strobes the author's desktop. Compile, emit, diff — never run.
- **Run `dune clean`.** It escapes a worktree and deletes the main checkout's
  `_build`. Run `dune` with `--root .` from inside your own worktree.
- **Kill a `flan dev` daemon you did not start.** The author keeps one attached
  to their editor.
- **Put `Co-Authored-By`, a `Claude-Session` trailer or any watermark in a commit.**

## Commits

`master` is the trunk. Lanes work in their own worktree and never merge or push;
the dispatching session merges. A commit message is one declarative sentence
saying what is now true, not what was done.

## Tests

A lane never runs the full `dune test`: it builds with `-j 2` and runs only the
programs and test executables its change touches, one at a time, and lists them in
its report. After about five lanes merge, one tester agent runs `dune test --root .`
on master and fixes what broke; grep its output for FAIL, since the exit code alone
has lied. `@checks` (`@page`, `@x86`, `@cells`), `@sanitize` and `@valgrind` are
slow and run only with the author's permission. ASan misses uninitialised stack
reads; `@valgrind` catches them.

## Evidence

Read the source, do not recall it — this repository and the reference clones
listed in `docs/REFERENCES.md`. Verify a brief's facts before building on them.

## Records

Keep only what the code cannot say.

- `TODO.org` — one `**` heading per item under a subsystem: `TODO` a gap, `NEXT`
  decided and queued, `WAIT` blocked (say on what), `CANCELLED` rejected with a
  one-line reason so it is not re-proposed, `DONE` only when the decision is not
  obvious from the code (two lines, what it rules out). On a merge conflict keep
  both sides.
- The reason for non-obvious code goes in a comment beside it.
- `docs/BUILT.md` holds only reasoning that spans several files.
- No handoff files.

## Reviews

Every lane gets an independent adversarial review before it merges: build and
run rather than read, measure both sides of a claimed fix, and reproduce any
number a lane reports.