# 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

(filled in as the work lands)