55 lines
2.2 KiB
Markdown
55 lines
2.2 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
|
|
|
|
`dune test --root .` must be green before a lane reports; grep its output for
|
|
FAIL, since the exit code alone has lied. `@checks` (`@page`, `@x86`, `@cells`),
|
|
`@sanitize` and `@valgrind` are slow and run once between batches of lanes, with
|
|
the author's permission, never inside a lane. 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.
|