A plan for tidying the root

docs/handoffs/HANDOFF-tidy.md

@@ -0,0 +1,25 @@
+# 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)