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.

HARNESS.md

@@ -70,6 +70,18 @@ change detection. Treat a *second* raise as evidence that something belongs in `
 two ceilings exist so that "core stops growing, ext rises" is observable, and that stops being true the moment
 leaves are allowed into core.
 
+**Context is a budget, and three pieces of it are mechanical.** The limit on this project is how much
+work fits in a session, so `docs/context-economy.md` holds the reading, searching and reporting
+disciplines — read the compressed form first, batch calls, script anything repeatable, never pay twice
+for the same bytes (ADR-0053). Three parts are enforced rather than trusted: `docs/surface.md` is
+regenerated and staged by the pre-commit hook and independently compared by `verify.sh`, so the map of
+the code cannot mislead (261 lines standing for 3,757 of source) and no one has to remember to run it;
+`CLAUDE_LOC_MAX` bounds the one file re-sent on every turn;
+and `./scripts/verify.sh --quiet` prints a verdict instead of forty-three lines, which is what the
+pre-commit hook now runs. The doc leads with a floor rather than the savings, because every cheap
+failure mode is also a token saving — not opening the owning doc, guessing a signature, reporting
+from a diff — and each of those has already cost this repo a defect.
+
 **The agent commits by itself, and tells you the first time.** Work is committed as part of the loop
 rather than on request (ADR-0052) — one commit per revertible unit, never a `push`. In a session where
 you have not asked for that, the first commit is preceded by a line saying so and naming the off
@@ -97,7 +109,8 @@ In order, cheapest first:
 1. `./scripts/verify.sh` — one command, tells you whether the thing is still coherent and whether
    `docs/state.md` has fallen behind the code.
 2. `docs/state.md` — what exists, the earn-it counters, the latent list, the commit it was last verified
-   against. This is the only doc that describes the present.
+   against. This is the only doc that describes the present. Its companion `docs/surface.md` is generated:
+   every declaration and its line, so you can find your way around without opening anything.
 3. `git log --oneline` — one revertible unit per commit, each body saying *why* (`conventions.md`). This is the
    real map of how the code got here.
 4. `/refresh-docs` — reconciles every doc against the actual code and reports drift, which is exactly the
@@ -193,7 +206,9 @@ that describe it, in the same change.**
   `gofmt`-only diff is exempt: it ships no behaviour, and failing it would only teach you `--no-verify`.
 - The gate is not optional. `scripts/hooks/pre-commit` runs it on every commit; enable once per clone
   with `git config core.hooksPath scripts/hooks`. `--no-verify` bypasses it, and the commit body should
-  say why.
+  say why. The hook also regenerates `docs/surface.md` and stages it, so a generated file is never
+  something you have to remember — and it refuses a commit with unstaged `.go` changes, because what it
+  generated describes the working tree rather than what you are committing.
 - `docs/decisions.md` registers every ADR number ever used, entries and withdrawals alike, so a citation
   can resolve to a decision or to a deferral but never to nothing.
 - `./scripts/verify.sh --list` names every gate that exists. A doc claiming enforcement is checkable