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>
/refresh-docs step 4 told the agent to check content-model.md's `[spec]` versus
`[live]` markers. The `[spec]`/`[arc1]` system was deleted in 1510a5f, and
`[live]` never existed at all — so the step was unperformable in both halves
while reading as a check. It now says what the doc actually is: no markers, every
sentence a claim to test, with the failure that has really shipped named
explicitly — a subcommand or gate described in the present tense that no code
dispatches. That is exactly what the previous commit found five of.
The feature-loop conflict table was worse than stale. Its Soft row treated "an
unbuilt `[spec]` section's suggested shape" as a convention to deviate from, and
its None row said a request matching a `[spec]` section should proceed with
nothing said about it. Those sections now live in ideas/exploration.md, whose own
header reads "Presence in this list is not permission to build" — so the skill
authorised building from parked ideas that the storage forbids. Both rows now
point at what a doc describes as built.
HARNESS.md gains the fact that explains the asymmetry, since it is now the only
place both marker systems are visible at once: architecture.md's STATUS markers
stayed and content-model.md's went, because a primitive's endgame is load-bearing
for the next decision while an unbuilt disk format is not. A marker inside a doc
the agent already has open still gets read, which is why the second system was
deleted rather than given a stricter rule.
3 files, +12/-6. No gate, threshold or counter moved.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
The verified-against sha could only ever be wrong. A commit cannot name itself,
so the line had to be written after the commit it described, which forced a
trailing `state:` commit every time — against conventions.md, which has always
said code, test, state.md row and ADR belong in one commit. Folding those
trailing commits away then left the sha naming a commit that no longer existed.
backup/pre-fold shows the pattern, and 8905686 is the commit that had to name
the survivor afterwards.
Git already knows when each file last changed. The gate now compares the last
commit touching docs/state.md against the last touching a .go file, and the
line is gone. Same intent, nothing to maintain, and no rewrite can invalidate it.
Also records two commit rules the human stated this session: state.md never gets
a commit of its own, and a minor change asked for just after a commit is amended
into it while it is unpushed rather than accumulating as noise.
bdeshiandClaude Opus 5