Joseph Ferano
57fe91f303
FIX.org, NEXT.md, DISCUSS.org, docs/DISCUSS.md and the session handoff at the root are one TODO.org now: 293 entries under seven subsystem headings, each carrying an org keyword that says where it stands. A DONE entry is a few lines saying what was decided and what that rules out; the reasoning that would not compress — the embedding spike and the four reports the hand-written x86 backend was built from — moved into docs/BUILT.md instead, and its entries point there in one line. Every entry was checked against the tree before it got a keyword, and the prose was wrong in both directions. Things the deleted files called open were built: the first-evaluation stall, main being redefinable, macro parameter lists, the type-limit constants, the array constructors, the byte fills, inc/dec, the discard's fontification, the Emacs buffers, rt_die's _exit, the backtrace surface, and the acceptance failure that could print and still exit zero. Things they called done were not: the backend reports' no-plan buckets had gone stale in the other direction, the value-dependent defvar was superseded rather than built, and macro-expansion source locations are on an unmerged lane, so that entry is NEXT and names the branch. Every comment that cited one of the five by name now cites a heading that exists, in TODO.org or in docs/BUILT.md. The session reports under docs/handoffs/ keep naming the files they worked on, because rewriting them would falsify what those sessions did; each carries a note saying where the content went.
131 lines
6.8 KiB
Markdown
131 lines
6.8 KiB
Markdown
# Tidying the repository root
|
|
|
|
A note from later: `FIX.org`, `NEXT.md`, `DISCUSS.org`, `docs/DISCUSS.md` and
|
|
the root `HANDOFF.md` have since been merged into `TODO.org` at the root, with
|
|
the reasoning that would not compress into `docs/BUILT.md`. This report is the
|
|
record of a session that moved those files around while they existed, so it
|
|
keeps naming them — including inside the grep patterns it ran. Read every
|
|
mention of them below as past tense.
|
|
|
|
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`
|
|
(since deleted — its decisions are in `TODO.org`, its reasoning in `docs/BUILT.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` (now
|
|
`TODO.org`), 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 |
|
|
|
|
(The file named in the middle column has since been deleted: its decisions live in
|
|
`TODO.org` and its reasoning in `docs/BUILT.md`. The names in this table are left as
|
|
this session wrote them.)
|
|
|
|
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` (now
|
|
`TODO.org`), 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` (now `TODO.org`) 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.
|