# 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:

```sh
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.