Claude Opus 5andbdeshi
7796b0d919
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.
Ideas — parked, not dropped
One file per idea, self-contained enough to resume cold. Nothing here is committed to; presence is not permission to build. An idea file exists so picking the thread back up costs one read instead of one re-derivation — the whole justification for writing it while the context is still in hand.
What goes where
| It is… | Where |
|---|---|
| an engine feature you might build (webmentions, gemtext, galleries) | docs/exploration.md catalog line, /leaf for a verdict |
| that same feature, but with a discussion worth not repeating | an idea file here, linked from the catalog line |
| the harness, agent workflow, token cost, tooling, process | here — exploration.md is engine-only |
| a decision already made | docs/decisions.md |
| a known code flaw deliberately unfixed | Latent list in docs/state.md |
| a durable fact, number, or link | reference/ |
Format
Five headings, present tense, terse. Copy an existing file. Required first lines:
# <title>
Status: parked | active | adopted → <where> | dropped: <one-line why>
Raised: YYYY-MM-DD
Keep dropped files — a one-line reason is the cheapest defence against relitigating it in four
months.
Reading discipline
Exploratory scratch code may live here too; verify.sh never formats, vets, builds or budgets it, so
it does not have to compile.
Out of agent context by default, this index included. A file is opened when the human names that
idea, not otherwise: not swept, not listed to see what is here, not cited unasked. This index is for
you, not the agent; verify.sh keeps it honest without reading it into context.
Index
- deferred-decisions.md — five pre-code ADRs demoted to intent; each returns when something implements it. parked
- specs-as-secondary-artifacts.md — optional per-feature specs, derived by default, plus the named-test convention. parked
- engine-design-review.md — open design decisions for a multi-type site; items graduate to ADRs one at a time. parked
- token-conservation.md — cut agent token cost without losing output quality. adopted →
docs/context-economy.md, except the subagent question