bdeshiandClaude Opus 5
ec6e9838f0
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>
2.9 KiB
Toolchain and external contracts
What this harness was built against, and which of those are contracts it depends on rather than incidentals. Recorded because a failure long after the fact is otherwise indistinguishable from a bug in the harness itself. Update the version line when you deliberately move; leave the rest alone.
Verified working: 2026-07-28
| Thing | Version then | Harness depends on |
|---|---|---|
| Go | 1.26.1 (darwin/arm64) | go list -f, go vet, go build, go test -race, gofmt -l. All stable since 1.11 |
| git | 2.53.0 | status --porcelain -uall, rev-list <sha>..HEAD -- '*.go', rev-parse --verify, core.hooksPath (2.9+) |
| Claude Code | 2.1.119 | the four formats below |
| bash | macOS default (3.2-era) + BSD userland | verify.sh avoids bashisms and GNU-only flags; grep -L, wc -l, xargs, awk are POSIX use |
The four agent-tooling contracts
These are the ones most likely to move, and the ones whose breakage looks like a harness bug:
CLAUDE.mdis loaded automatically from the repo root on every request. If that stops being true, nothing enforces the constitution and the agent will behave like a stock assistant..claude/skills/<name>/SKILL.md— a Markdown file in a directory named for the skill, which fires on request content matching its description. The feature loop depends on firing without being invoked; if skills come to need explicit invocation, the loop silently stops applying..claude/commands/<name>.md— Markdown with a YAML frontmatterdescription:, invoked as/<name>,$ARGUMENTSsubstituted. Used by/verify,/audit,/leaf,/refresh-docs,/adr,/invariants..claude/settings.json— apermissionsobject withallow/ask/denyarrays ofTool(pattern)strings. Only a convenience: if the schema changes, the harness still works, you just get more prompts.
Not depended on
No CI service, no container registry, no language server, no linter binary, no package manager beyond
go mod. The Makefile is a convenience wrapper only: every target is one go or verify.sh command,
and the gate never invokes make, so a machine without it loses nothing but typing.
verify.sh runs offline with nothing but Go and git on PATH, which is deliberate — the gate must work
on a machine you have not configured for two years.
VERIFY_DOCKER=1 adds a container build step and needs docker; it is opt-in and off by default.
If something breaks after a long absence
Check in this order, cheapest first: go version and git --version against the table above; then
whether verify.sh fails in the documentation block (a harness-internal problem) or the go block (a
toolchain or code problem); then whether the agent is still reading CLAUDE.md at all — ask it to quote
a hard rule, and if it cannot, the problem is contract 1 and nothing downstream will behave.