57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
# 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.
|