|
|
|
@@ -0,0 +1,105 @@
|
|
|
|
|
---
|
|
|
|
|
topic: how we work
|
|
|
|
|
status: accepted
|
|
|
|
|
date: 2026-08-31
|
|
|
|
|
deciders: jochen
|
|
|
|
|
reconstructed: false
|
|
|
|
|
extends: 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`](../README.md) names the gap in the place the claim used to sit, and
|
|
|
|
|
[ADR 0019](0019-how-this-repository-works.md)'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`](../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md).
|
|
|
|
|
|
|
|
|
|
**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`](../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](0004-a-node-and-how-it-joins.md)) — 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`](../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md) —
|
|
|
|
|
the gap, the two measurements, and why closing it early was refused
|
|
|
|
|
- [ADR 0019](0019-how-this-repository-works.md) — the promise this amends
|
|
|
|
|
- [`README.md`](../README.md) — the objection, and the gap named where the claim used to sit
|