make context a budget the harness enforces

Adopts ideas/token-conservation.md, parked 2026-07-28, plus the disciplines
the human added: read the compressed form first, discover by mechanism,
shrink output at the source, never pay twice for the same bytes.

docs/context-economy.md owns all of it and leads with a floor, because
every cheap failure mode is also a token saving — skipping the owning doc,
guessing a signature, reporting from a diff, thinning a test — and each has
already cost this repo a defect. Frugality is for presentation and
discovery, never for the artifact or the evidence.

Mechanical, not remembered:

- scripts/surface.sh generates docs/surface.md — every top-level
  declaration with its line, 261 lines standing for 3757 of source. The
  pre-commit hook regenerates and stages it, so it cannot be stale, and
  verify.sh compares independently for a clone that never set
  core.hooksPath. The hook refuses a commit with unstaged .go changes,
  since what it generated describes the working tree, not the commit.
- verify.sh --quiet: 48 lines of gate output become 1. The hook uses it.
- CLAUDE_LOC_MAX=150, the only budget billed per turn rather than per read.

Both new gates were watched failing before being kept: a doctored
surface.md, and CLAUDE_LOC_MAX temporarily set to 5.

state.md's inventory loses its LOC column. It had already drifted on six
files (content.go 381→450, render.go 447→454, web.go 206→217, check
216→223, watch 129→137, chrome 105→110) which is what a number written in
two places does; the generated file owns sizes now, the table owns purpose.
The subagent question is recorded there as the one open decision, with the
case for and against written out in the idea file.

docs/decisions.md

@@ -788,3 +788,28 @@ said. `conventions.md` "Git" owns what one commit contains; `CLAUDE.md` §4 owns
 Revisit if: the log fills with commits nobody would revert separately — then the unit is wrong, not the
 automation; or the human wants a review gate before anything lands, which is a different default, not a
 tweak to this one.
+
+## ADR-0053 — Context economy is a doc with a floor, plus three gates
+Date: 2026-08-01 · Status: accepted (adopts `ideas/token-conservation.md`)
+Decision: `docs/context-economy.md` owns how the agent spends context — read the compressed form first,
+fewer turns before fewer bytes, script anything repeatable, shrink output at the source, never pay twice
+for the same bytes. Three parts are mechanical rather than remembered: `scripts/surface.sh` generates
+`docs/surface.md`, the pre-commit hook regenerates and stages it while `verify.sh` compares it
+independently, `CLAUDE_LOC_MAX=150` bounds the file re-sent every turn, and `verify.sh --quiet` prints
+only what needs acting on (the hook uses it). Generated artifacts are produced by the hook, never by
+memory; the hook refuses a commit with unstaged `.go` changes, since what it generated describes the
+working tree rather than the commit.
+Why: the binding constraint is context per session, not typing speed, so wasted bytes are features not
+built. The measurements that decided the shape: `go doc` on `internal/content` is 38 lines against 1,579
+of source, and `surface.md` is 261 against 3,757. The doc leads with a floor because every cheap failure
+mode is also a saving — skipping the owning doc, guessing a signature, reporting from a diff, thinning a
+test — and each has already cost this repo a defect. Generated-and-gated rather than hand-written,
+because an index nobody regenerates is worse than no index: it is confidently wrong.
+Consequence: cheap — a green gate run is 2 lines instead of 43, "where does X live" is one grep of a
+tracked file, and the disciplines are auditable in one place. Expensive — a fourth generated artifact to
+keep honest, one more budget to raise deliberately, and 261 lines of committed noise in every diff that
+adds a function. Deliberately *not* mechanical: nothing can detect a redundant read, so most of the doc
+is discipline, and it says so instead of implying enforcement (rule 8).
+Revisit if: the surface grows past a few hundred lines, in which case it is per-package files rather than
+one; or `surface.md` churn starts drowning real diffs, which is the argument for generating it on demand
+instead of tracking it.