docs/content-model.md opens with "Engine specification". It is also where the
rule lives that a leading underscore makes a file unaddressable — and the human
who owns this site did not know that rule, because nothing in this repository is
addressed to an author. Twelve documents named docs/ while being exclusively
about building the parser is a signpost pointing at the wrong room.
Naming the directory for its audience makes the gap visible instead of hiding it.
docs/ is now reserved and deliberately absent: an empty docs/ is an honest
statement that end-user documentation does not exist, where docs/ full of parser
specs was a claim that it did.
HARNESS.md stays at the root. Root holds the three entry points — README.md for a
human, CLAUDE.md for an agent, HARNESS.md for whoever maintains the machine — and
harness/README.md is the map of the directory, so moving the guide inside would
have collided with it for nothing.
Mechanical and wide: 100 path references across 24 files. Every verify.sh gate
that names a doc by path, the directory lists the dangling-path and ADR-number
gates scan, surface.sh's output target, the Makefile, CLAUDE.md's read order, the
skill, four commands, and two Go package comments. A first pass with a shell loop
silently edited only four files and the rest still said docs/; the fix was to
write the file list out and check the remaining count was zero rather than trust
the loop's exit status.
No rule, threshold, gate or obligation moved — this is a rename, and the gates
demonstrated it twice: they stayed green on the new paths, and the ADR-number gate
caught ADR-0082 before the entry existed.
Deferred, both on the human's call: the end-user documentation site itself, which
wants its own decision about where it lives and whether its claims are gated; and
moving examples/ under docs/, since demo-site is a live site root that verify.sh,
the coverage test and make demo all point at, and moving it would couple a rename
to a design nobody has made.
31 files, +146/-106.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
HARNESS.md described how the ceilings got where they are — a paragraph of
changelog that grew with each raise. The ADR log is where history belongs, so
the section now states what the two ceilings are for, where the values live, and
how to read a raise. Any doc that narrates its own edits will do this again.
theme-contract.md explained parse order three times: once in the fragments
section, once under the stability rule, once under overriding. Once now, with
the other two pointing at it.
content-model.md carried a marker system — `[arc1]` build now, `[spec]` recorded
intent, plus a standing instruction never to build from a `[spec]` section. The
better answer than a stricter marker is no marker: the doc now describes only
what the parser accepts, and the shapes nobody has asked for moved to
ideas/exploration.md, which is storage and out of context by default. There is
nothing left to build speculatively from, so nothing needs to say so. 518 lines
to 469, and rule 6 plus the leaf/trunk test already cover the rest.
A sweep for filler phrasing found almost none — the prose was already tight — so
that part is two rhetorical tics rather than the cull expected. Reporting it
honestly matters more than manufacturing a diff.
No rule, gate, threshold or obligation moved.
Two structural changes, both about what an agent may pull into context.
exploration.md catalogues engine features nobody has asked for. That is storage,
not working material, so it moves to ideas/ where nothing sweeps it and it is
opened only when named — the same rule the other parked material already
follows. Six references repointed; the ideas gates then demanded an index line
and a status, and both were supplied rather than exempted.
build-queue.md was 516 lines, nearly all of it entries 0-23 finished months of
work ago, with the plan buried at the top. It becomes .scratch/continue.md at
49: where the code is, what is planned, and the findings worth carrying that no
doc owns — chiefly that silent damage to prose is this engine's recurring
failure mode, and that three defects this arc were invisible to curl.
Docs and HARNESS point at the new names. No rule, gate or threshold changed.
bdeshiandClaude Opus 5