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.