hq/02-DECISIONS/0025-the-design-record-is-read-not-copied.md

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
how we work	accepted	2026-08-31	jochen	false	02-DECISIONS/0019-how-this-repository-works.md

25. The design record is read where it is written, never copied to be found

Context

These documents cannot be found by searching the mesh's memory, and never could. Checked on 2026-08-23 and again on 2026-08-31, against both the symptom-indexed store and the structured archive, using a decision record's full title and a distinctive phrase from a design document: no result, no partial match, no stale copy.

That matters because of what was promised. The objection to giving this material its own repository was that the mesh already has a knowledge store, and a second one repeats the mistake that store was created to fix. The answer offered was indexing rather than location — that these documents would be returned beside everything else in a search, so where they were authored became a separate question. The indexing was never built.

The claim has since stopped being load-bearing, which is why this is a decision rather than an incident. README.md names the gap in the place the claim used to sit, and ADR 0019's reasoning rests on cadence, reviewers and scope — none of which depend on being searchable from elsewhere. What remained was an unbuilt capability and an open question, recorded as 04-ISSUES/006.

A signpost was added on 2026-08-31 and measured. One entry in the mesh's memory naming what lives here and when to come looking. A search for design records, decisions, repository returns it; a search phrased the way somebody actually asks — why is the mesh built this way — returns nothing, because the store matches terms and not meaning. Reachable is not the same as surfacing, and the measurement is what established which one a signpost buys.

Considered Options

1. A one-way sync into the mesh's memory. A job reads this repository on a schedule and writes the documents into the searchable store. It works with what exists today and needs nothing built first. Rejected, because it creates a second copy of every document, and the failure mode of a derived copy is the one this repository is least able to tolerate: the copy that is searched quietly stops matching the copy that is edited, and the enforced one wins. A design record that has silently diverged from the reasoning it claims to carry is worse than one that cannot be found — the first misleads, the second merely fails.

2. Leave the signpost and close nothing. Honest, free, and it keeps the gap visible. Rejected as an end state, though it is what stands until the option below exists. It answers only for a reader who already suspects these documents exist, which is precisely not the reader the mesh's memory is designed for.

3. An agent reads this repository directly, and the search consults it. Nothing is copied. Adopted.

Decision

The design record is read where it is written. Retrieval is an agent reading this repository, not a copy living in a second store — and a search of the mesh's memory consults that agent, so what it knows appears beside ordinary results rather than only when it is asked.

Both halves are the decision. The first alone is merely a reader, and would leave this repository reachable but not surfacing — the state measured above. The second half is what discharges the promise that these documents are returned beside everything else.

There is no copy, and that is the point. No sync, no schedule, no reconciliation, and nothing that can drift, because there is only ever one of each document. It is also always current, including for work that is not yet committed.

The direction of reading is one-way and stays that way. The agent reads this repository and answers from it. Nothing flows back: this repository is public, the mesh is not, and a return path would be how installation-specific detail arrives into documents that must not carry it (README.md).

Consequences

This repository stops being a fourth knowledge system, properly. The original objection was about adding a knowledge system. An agent with read access adds no store at all — which answers the objection more completely than the indexing that was promised, rather than merely as well.

ADR 0019's promise is amended, not satisfied. It said these documents would be indexed. They will not be. They will be read, and the search will ask. The commitment that survives is the one that mattered — that a searcher finds them without already suspecting they exist — and the mechanism behind it is different from the one named.

It is gated on an agent that does not exist yet. Until it does, the signpost is what stands, and this repository is reachable rather than surfacing. That is a known and stated gap, not a silent one — and the gap is now a build task with a decided shape rather than an open question.

The search must degrade honestly. When the agent cannot be reached, a search has to say that this material was not consulted. A result set that silently omits it looks identical to one where nothing matched, and silence and success must never look alike (ADR 0004) — the rule this repository has now paid for twice.

A rule states how it is checked, and this one is checkable. The check is the measurement that produced this record: search the mesh's memory for a phrase that appears only in a design document here, and require it back. That check fails today, deliberately, and passing it is what closes 04-ISSUES/006.

References

• 04-ISSUES/006 — the gap, the two measurements, and why closing it early was refused
• ADR 0019 — the promise this amends
• README.md — the objection, and the gap named where the claim used to sit