bdeshi
9359478789
So the thing can be built and run without reading the harness. Eight targets, each one go command or verify.sh; make help lists them. README gains the four lines someone actually needs, and says a site root is a directory the binary is pointed at rather than something in this repo. make is recorded in toolchain.md as a convenience: the gate never invokes it, so a machine without make loses nothing but typing.
49 lines
2.9 KiB
Markdown
49 lines
2.9 KiB
Markdown
# 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:
|
|
|
|
1. **`CLAUDE.md` is 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.
|
|
2. **`.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.
|
|
3. **`.claude/commands/<name>.md`** — Markdown with a YAML frontmatter `description:`, invoked as
|
|
`/<name>`, `$ARGUMENTS` substituted. Used by `/verify`, `/audit`, `/leaf`, `/refresh-docs`, `/adr`,
|
|
`/invariants`.
|
|
4. **`.claude/settings.json`** — a `permissions` object with `allow` / `ask` / `deny` arrays of
|
|
`Tool(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.
|