flan/docs/handoffs/HANDOFF-tidy.md

Tidying the repository root

The root had thirty-odd files in it, nine of them session reports sitting at the same level as the language specification, and a README is about to point a newcomer at that. This is the plan and, below it, what actually happened.

The plan

1. git mv the nine HANDOFF-*.md into docs/handoffs/, and ../DISCUSS.md, ../BUILT.md, ../PORTING.md, ../SPIKE-GENERICS.md, ../REFERENCES.md and ../overview.md into docs/. These are written once and read occasionally.
2. Leave plan.org, spec-memory.md, spec-conditions.md, NEXT.md, the .flan scratch programs and the build files where they are: they are cited by bare filename from source comments in dozens of places, and moving them would be a large rewrite for no gain.
3. Rewrite every citation of a moved file, zone by zone — a flat substitution is wrong, because a citation inside docs/ should stay bare while the same citation in lib/ needs the docs/ prefix.
4. Verify by resolving, not by grepping: for every cited path in the repository, check it exists relative to the citing file or to the root.
5. Write docs/README.md saying which of these documents are still true.

What happened

The moves. Fifteen files, all with git mv so git log --follow still reaches their history. Nothing else moved.

The citations. 238 of them across 52 files, rewritten by zone. The zones matter and a repository-wide substitution would have corrupted two of them:

Citing file lives in	DISCUSS.md and its siblings	HANDOFF-*.md
the root, lib/, test/, emacs/, spike/, examples/, vendor/	docs/DISCUSS.md	docs/handoffs/HANDOFF-x.md
docs/	unchanged — they are siblings	handoffs/HANDOFF-x.md
docs/handoffs/	../DISCUSS.md	unchanged — siblings again

Most of the citations are prose inside a source comment rather than a link; there is not a single markdown link among the fifteen moved documents. So the rewrite is a rewrite of comments, and in lib/x86.ml, lib/build.ml and test/test_reload.ml — which another lane is editing at the same time — every touched line is a comment line.

The verification. Grep cannot tell you a rewrite is finished, because a grep for DISCUSS.md matches docs/DISCUSS.md too. So the check resolves instead: every path-shaped citation in the repository is looked up relative to the file that wrote it and relative to the root, and anything that resolves to neither is reported. 817 citations checked. The only failures are seven mentions of HANDOFF-f1.md, HANDOFF-f2.md and HANDOFF-f3.md in ../../NEXT.md, which were already dangling before this work — the prose around each one says the file was deleted — and one false positive where the pattern caught "$root/NEXT.md" out of a shell variable.

The judgement calls

MY-NOTES.org and conditions.org stay at the root. MY-NOTES.org is the author's scratch — questions to himself about the standard library, in the second person. conditions.org is a live cheatsheet, not a report, and it is the entry point to conditions-play.flan beside it. Neither is a document that belongs in a directory of finished reports, and personal files are best left where their owner put them.

conditions-play.flan stays at the root. The brief said to move it to spike/ if nothing referenced it. Three things do: conditions.org:5 tells the reader to run it, NEXT.md:1306 lists it as the program to poke conditions with, and .gitignore has an anchored /conditions-play for the executable it builds to. It is also not shaped like the rest of spike/, which is four self-contained experiment directories with their own runners, not a home for a loose .flan file. It is a demonstration that belongs next to the cheatsheet that points at it.

.flan-dev.sock is not in this worktree. The stale one is in the author's main checkout, which a worktree-isolated lane cannot reach. The ignore pattern is added here so the next one never shows up in git status; the existing socket is the author's to remove.

.gitignore. Five entries at the bottom of the file — .claude/, probe, probe.c, /forms.so, _hist/ — were uncommented stragglers in a file where everything else explains itself. They are grouped and explained now, and .flan-dev.sock is added. No pattern was removed or changed in meaning.

Verification

• dune build --root . exits 0.
• dune test --root . --force reports 232 checks, 0 failures.
• spike/x86/survey.sh, run detached, reports 103 MATCH, 0 DIFFER, 0 REFUSED, 0 NOX86 and 38 SKIP — the baseline, unchanged.

The resolver reports sixteen unresolved citations and all sixteen are expected. Seven are the deleted HANDOFF-f1.md, HANDOFF-f2.md and HANDOFF-f3.md in ../../NEXT.md, which the prose around them already calls deleted. One is a false positive where the pattern caught "$root/NEXT.md" out of a shell variable in web/examples/quotes.sh. The other eight are in this file: the HANDOFF-x.md placeholders in the zone table above, and DISCUSS.md quoted bare to explain why a grep cannot verify this work. None of them is a path.

The branch clutter — reported, not acted on

git branch --list 'worktree-agent-*' returns 113 branches. 111 are fully merged into dev-loop. 89 of them have a worktree currently registered under .claude/worktrees/, and deleting one of those would break the harness. The two unmerged branches are the two lanes running right now.

That leaves 24 branches that are both merged and have no live worktree, and those are the only ones safe to delete:

comm -23 \
  <(git branch --merged dev-loop --format='%(refname:short)' --list 'worktree-agent-*' | sort) \
  <(git worktree list --porcelain | sed -n 's|^branch refs/heads/||p' | sort) \
  | xargs -r git branch -d

git branch -d rather than -D on purpose: it refuses anything that turns out not to be merged after all. The 89 with live worktrees want git worktree prune and a decision about the directories first, which is the author's call and not a cleanup to run blind.