diff --git a/docs/handoffs/HANDOFF-tidy.md b/docs/handoffs/HANDOFF-tidy.md new file mode 100644 index 0000000..63b5a97 --- /dev/null +++ b/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)