117 lines
6.1 KiB
Markdown
117 lines
6.1 KiB
Markdown
# 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.
|