jschoubben
5e83ac2c22
Jochen: a normal application has 3-5 ADRs, maybe 10 for a large one, and we are at 65. Fair, and the cause is mine -- I recorded every FINDING as a decision rather than every fork in the road. Two merges, both cases where one decision had been split across many records because it was taken over several days rather than at once. 0019 absorbs ten records about how this repository works: what it is and that it is public, the folder flow, the two design layers, the issue front door, status in frontmatter, playbooks, the naming rule, the product name. Those were never ten decisions -- they were one, seen from ten angles as the repository took shape. 0016 absorbs the five about the lab: a node is a virtual machine, a router is scenery, a scenario declares the underlay, a scenario is a closed address space, and the two scenario classes. Same pattern -- one design, split by the order it was worked out in. The consolidated 0019 also raises the bar for what earns a record, since that is what produced 65: a record is warranted when there is a genuine fork -- a direction reversed, an alternative that will be proposed again, something contested. A finding is not a decision, and a bug is certainly not. Everything else belongs in the design document where the reasoning is actually read. The checker earned its place here. Deleting nine records left 13 dangling links across the repository and it named every one, including in AGENTS.md. Nothing was found by reading. Remaining clusters worth the same treatment: the host (8 records), delivery (5), modules (6), connectivity (4), substrate and control plane (4). That would be 52 down to roughly 30.
91 lines
4.3 KiB
Markdown
91 lines
4.3 KiB
Markdown
---
|
|
status: open
|
|
opened: 2026-08-23
|
|
located-in: [hal, hq]
|
|
fixed-by:
|
|
amended-design:
|
|
---
|
|
|
|
# 006 — This repository is not indexed into the knowledge base, and the claim that it is holds up a decision
|
|
|
|
## Symptom
|
|
|
|
[`README.md`](../../README.md) states, as the answer to the objection against creating this
|
|
repository:
|
|
|
|
> These documents are still indexed into the knowledge base, so `recall_search` returns them
|
|
> beside everything else. One source, many surfaces — which was always the actual requirement.
|
|
|
|
Searching the knowledge base for this repository's content returns nothing.
|
|
|
|
## Evidence
|
|
|
|
Verified 2026-08-23, two searches against the mesh's operational memory:
|
|
|
|
| Query | Result |
|
|
|---|---|
|
|
| The full title of a decision record in this repository | No results |
|
|
| A distinctive phrase from the decision ledger | No results |
|
|
|
|
No entry, no partial match, no stale copy. The indexing does not exist and appears never to
|
|
have existed.
|
|
|
|
## Why this is an issue and not a task
|
|
|
|
The claim is **load-bearing**. Decision 27 separates HQ into its own repository, and the
|
|
objection it answers was that a fourth knowledge system repeats the mistake the mesh's
|
|
knowledge consolidation was created to fix. The recorded answer is *"indexing, not location"* —
|
|
that the split is safe **because** these documents remain searchable alongside everything else.
|
|
|
|
Without the indexing, the objection stands unanswered and this repository is precisely the
|
|
fourth knowledge system it was argued not to be. Either the indexing is built, or decision 27's
|
|
reasoning is amended to something that is true.
|
|
|
|
It is also, exactly, the failure this repository names in its own rules: a document stating a
|
|
rule about the mesh must say how the rule is checked. This one stated a mechanism and nobody
|
|
checked it — including in the same commit that wrote the rule.
|
|
|
|
## Open questions
|
|
|
|
- Where would the indexing run? The operational memory is written through a mesh capability;
|
|
is this a periodic sync of a repository into it, or a search surface that reads the
|
|
repository directly?
|
|
- Which store — the flat symptom-indexed memory, the structured archive, or both? They have
|
|
different lifecycles ([`03-DESIGN/00-as-is/07-knowledge.md`](../../03-DESIGN/00-as-is/07-knowledge.md)),
|
|
and this content is governed rather than incidental.
|
|
- Public repository, private mesh: the sync direction must not become a path for mesh-specific
|
|
content to arrive **into** these documents.
|
|
|
|
## Proposed direction — Nox is the search
|
|
|
|
*Added 2026-08-23.* Rather than syncing these documents into the knowledge base, **Nox
|
|
([ADR 0019](../../02-DECISIONS/0019-how-this-repository-works.md)) works from within this
|
|
repository and holds its knowledge directly.** Retrieval becomes an agent reading the source,
|
|
not a copy living in a second store.
|
|
|
|
This is a better answer than the one the README originally promised, on three counts:
|
|
|
|
- **No sync, so no drift.** The failure mode of a derived copy — the enforced copy winning
|
|
while the reasoned one quietly stops being true — cannot occur when there is no copy.
|
|
- **It dissolves the original objection properly.** The argument against a separate repository
|
|
was that it adds a fourth knowledge *system*. An agent with read access adds no store at all.
|
|
- **It is always current**, including for uncommitted work in progress.
|
|
|
|
**But it changes the promise, and that is worth stating rather than glossing.** ADR 0019's
|
|
answer was that these documents would be returned *beside everything else* in a symptom search.
|
|
An agent that must be **asked** is reachable; it is not surfacing. The two differ in exactly
|
|
the case the operational memory is designed for: someone debugging an error who has no reason
|
|
to think HQ knows anything about it.
|
|
|
|
So the open question narrows to one thing:
|
|
|
|
> When a symptom is searched and the answer happens to live in a design document or a decision
|
|
> record here, does the searcher find it without already suspecting it exists?
|
|
|
|
If Nox is the only path, the answer is no, and the reasoning in ADR 0019 needs amending rather
|
|
than satisfying. If Nox also contributes what it knows to a symptom search — or the search
|
|
consults Nox — the answer is yes and the original promise holds.
|
|
|
|
That is a design question for Nox, not a defect in this repository, and it should be settled
|
|
before ADR 0019 is treated as answered.
|