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.6 KiB
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) | ideas/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 — ideas/exploration.md is engine-only |
| a decision already made | harness/decisions.md |
| a known code flaw deliberately unfixed | Latent list in harness/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
- exploration.md — the catalog of engine features nobody has asked for, with leaf/trunk verdicts. catalog
- token-conservation.md — cut agent token cost without losing output quality. adopted →
harness/context-economy.md, except the subagent question
It lives here rather than in harness/ because a catalogue of things nobody has asked for is storage, not
working material: keeping it out of harness/ keeps it out of the set an agent may pull in on demand.