diff --git a/02-DECISIONS/0025-the-design-record-is-read-not-copied.md b/02-DECISIONS/0025-the-design-record-is-read-not-copied.md new file mode 100644 index 0000000..7d4e5b3 --- /dev/null +++ b/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 diff --git a/02-DECISIONS/README.md b/02-DECISIONS/README.md index b3a5767..b99144c 100644 --- a/02-DECISIONS/README.md +++ b/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) diff --git a/04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md b/04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md index 56c75be..7c8280e 100644 --- a/04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md +++ b/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.