jschoubben
e823cc1cc5
Decides the question 006 narrowed to. An agent reads this repository directly and the search consults it, so these documents surface beside ordinary results instead of only when somebody already suspects they exist. A scheduled sync into the mesh's memory was the option that works with what exists today, and lost on the ground this repository can least afford: it makes a second copy, and the copy that is searched quietly stops matching the copy that is edited. 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. Amends what 0019 promised rather than satisfying it: these documents will not be indexed, they will be read. The commitment that survives is the one that mattered — that a searcher finds them without already suspecting they exist. Gated on an agent that does not exist yet, so 006 stays open on the build with a decided shape. What closes it is a check that fails today by design: search the mesh's memory for a phrase that appears only in a design document here, and require it back.
106 lines
6.0 KiB
Markdown
106 lines
6.0 KiB
Markdown
---
|
|
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
|