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.fln is a different file and may be edited normally.
Execute examples/*.fln, sand.fln, 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.

2.4 KiB Raw Blame History