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

@@ -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

02-DECISIONS/README.md

@@ -97,6 +97,7 @@ python3 00-META/checks/index.py            fail if stale
 
 - **0009** — [Modules and the graph](0009-modules-and-the-graph.md)
 - **0010** — [Delivery](0010-delivery.md)
+- **0024** — [Model access is a provision, and a licence is a thing with a name](0024-model-access-is-a-provision.md)  *(proposed)*
 
 ### How it is built
 
@@ -119,5 +120,6 @@ python3 00-META/checks/index.py            fail if stale
 - **0021** — [HQ is the source of the mesh constitution](0021-hq-is-the-source-of-the-constitution.md)
 - **0022** — [The constitution absorbs what is already enforced](0022-the-constitution-absorbs-what-is-enforced.md)
 - **0023** — [The approval is the checkpoint, not the second pair of hands](0023-approval-is-the-checkpoint.md)
+- **0025** — [The design record is read where it is written, never copied to be found](0025-the-design-record-is-read-not-copied.md)
 
 <!-- index:end -->

04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md

@@ -3,7 +3,7 @@ status: located
 opened: 2026-08-23
 located-in: [hal, hq]
 fixed-by:
-amended-design:
+amended-design: 02-DECISIONS/0025-the-design-record-is-read-not-copied.md
 ---
 
 # 006 — This repository is not indexed into the knowledge base, and the claim that it is holds up a decision
@@ -136,3 +136,22 @@ about how the knowledge system works, not a defect to be fixed quietly.
 
 **Marking it resolved while the indexing does not exist would be the failure this repository was
 created to name**, one folder away from where it names it.
+
+## The direction is decided
+
+*2026-08-31.* **The agent reads this repository; nothing is copied.** Recorded as
+[ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md), which also amends
+what [ADR 0019](../../02-DECISIONS/0019-how-this-repository-works.md) promised: these documents
+will not be *indexed*, they will be *read*, and the search consults the agent so its answers
+appear beside ordinary results.
+
+A sync was the option that works with what exists today, and it was rejected on the one 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*.
+
+**So the open question above is answered, and this report stays open on the build.** What closes
+it is the check ADR 0025 names — search the mesh's memory for a phrase that appears only in a
+design document here, and get it back. That check fails today by design.
+
+**What stands until then** is the signpost, and the honest description of it: reachable, not
+surfacing.