flan/CLAUDE.md

Working in this repository

For any agent working here, including a lane in its own worktree. These are standing rules, not preferences. Where a rule has a reason, the reason is given once — the rules without one are the ones that have already cost something.

Never

• Never touch anything under /home/joe/Development/fnm/. That is the author's own working copy of the falling-sand game, open in an editor with a live session attached. fnm/flan/sand.flan is not the same file as this repository's sand.flan and is never to be read-and-written-back, moved or edited. The copy in this repository is ordinary tracked source and may be edited like any other file.
• Never execute examples/*.flan, sand.flan, or anything that links raylib. They open a window on the author's desktop, which strobes it. Compile them, emit them, diff them — never run them.
• Never run dune clean. It walks up out of a worktree and deletes the main checkout's _build, which takes the author's flan binary with it. This has happened. Run dune with --root . from inside your own worktree.
• Never kill a flan dev daemon you did not start. The author keeps a live one attached to their editor all day. Orphans from finished lanes are fair game; anything whose cwd is under fnm/ is not.
• Never put a Co-Authored-By, a Claude-Session trailer, or any other watermark in a commit message.

Commits and branches

master is the trunk and tracks origin/master. Lanes work in their own git worktree off it and do not merge or push — merges are resolved by the session that dispatched the lane.

A commit message is a single declarative sentence in the repository's voice, saying what is now true rather than what was done: "A thunk named for the order it was minted in is a different signature after a reorder", not "fix thunk naming bug". A body is for the reasoning, when there is any.

Tests

dune test --root . is the suite and takes seconds. Run it constantly; it must be green before a lane reports.

dune build @checks is @page, @x86 and @cells — the reference page's examples still compile and print what the page says, the hand-written x86 backend still agrees with LLVM, and a --dev build still calls through its indirection cells. @sanitize and @valgrind run the corpus under ASan/UBSan and memcheck and take tens of minutes.

Those three stay out of a lane's own run. They are swept in a batch after several lanes have merged, and the fixes are batched with them. Keeping the default run fast is deliberate: a suite that takes tens of minutes is a suite nobody runs.

Note that ASan does not see a stack-lifetime bug — uninitialised stack reads need @valgrind.

Evidence

Read the source, do not recall it. docs/REFERENCES.md lists the reference clones on this machine — Odin, SBCL, Zig, Carp, clojure-mode, CIDER, raylib and the rest — and what each one answers. A claim in these notes that came from one of them was read out of the clone; the ones that were recalled instead have been wrong before.

The same applies to this repository. Cite a file and a line because you opened it. When a brief hands you a list of facts, verify them before building on them — a brief written from a stale tree has sent a lane a full day in the wrong direction.

Diagnostics

Elm's shape: the source line, a caret, what the compiler understood, and the fix named. Beyond that:

• A message is written for someone who has never used Flan and does not know its history. Never "X is now Y", never "X was renamed", never our rationale. If defvar no longer exists, the message says defvar does not exist — not that it became something else.
• The clauses come in one order: what the compiler understood, then what conflicts with it, then the fix — "expected i32, found string".
• Every suggestion a message prints must compile.
• An assertion about the compiler's own invariants is prefixed internal: and says it is a compiler bug. A user never caused one.

Writing

User-facing prose — the README, web/index.html, the Emacs manual — is plain. Odin's website is the reference: declarative rather than second-person, the concept defined before the mechanics, the code example after the prose that frames it, and rationale given its own subsection rather than mixed in.

No aphorisms, no closing lines built for effect, no rhetorical inversions. If a sentence's only content is its own style, cut it. This applies to reports and commit messages as much as to documentation.

The records

• TODO.org — every decision, question and known gap, one ** heading each under a subsystem heading, with an org keyword saying where it stands: TODO for a gap, NEXT for what is queued, WAIT for what is blocked and on what, DONE for what was settled, CANCELLED for an idea considered and rejected. A lane records its decision here, as a few lines saying what was decided and what it rules out — never the argument and never the measurements. On a merge conflict in this file, keep both sides: two lanes recording two decisions is not a conflict.
• docs/BUILT.md — why the parts that exist are shaped the way they are. The largest and most load-bearing document here. Reasoning that will not fit in a few lines goes here, and TODO.org carries one line pointing at it.
• docs/handoffs/ — one report per finished work session.
• docs/README.md indexes all of it.

A CANCELLED entry is not housekeeping. An idea rejected without a record is an idea that gets re-proposed, so the one-line reason is the whole value of it.

The shape of the work

The author dogfoods the language in a separate project, hits friction, and reports it. Work is dispatched as parallel lanes in isolated worktrees; every lane is reviewed by an independent agent before it merges; the dispatching session resolves the merges.

A review is adversarial. Verify by building and running rather than by reading, measure both sides of a claimed fix, and say what you actually measured. A lane that reports a number you did not reproduce is a lane with a number you should reproduce.