Remove the decision records and research efforts, which the knowledge base now holds whole (issue 426)
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; it…
mesh/delivery superseded: a newer head of the same pull request

ADR 0290 rule 9: once the import is checked record by record, hq keeps no copy.
The records and efforts are removed; every link or path to them reads "ADR NNNN" or
"research NNN"; a design's decisions: lists "ADR NNNN". 02-DECISIONS keeps a pointer
README with the reading order's six topics, which the knowledge base reads through the
records module; 01-RESEARCH keeps a pointer README. The checks drop the rules that
judged records (the knowledge base holds each at propose; checks/README.md says where)
and refuse a record written here again. Playbooks 01 and 02 and the skills write and
read records with the knowledge base's verbs.
This commit is contained in:
2026-10-11 12:56:09 +02:00
parent 76b346afcd
commit 418261213c
768 changed files with 2435 additions and 57645 deletions
+26 -20
View File
@@ -1,8 +1,9 @@
# Agent instructions — Novox HQ
This repository is the source of truth for Novox's mission, research, design and decisions —
today almost entirely those of **Novox Mesh**, its first product ([ADR 0019](02-DECISIONS/0019-how-this-repository-works.md)). Implementation lives in the code repositories (see
[`00-META/repos.md`](00-META/repos.md)).
This repository is the source of truth for Novox's mission and design —
today almost entirely those of **Novox Mesh**, its first product (ADR 0019). Its decision records and
research efforts live in the knowledge base, the seat `knowledge-base` (ADR 0290), and nowhere here.
Implementation lives in the code repositories (see [`00-META/repos.md`](00-META/repos.md)).
Before changing anything here, read the playbooks in
[`00-META/process/`](00-META/process/) — every workflow (research, graduation, design
@@ -16,7 +17,7 @@ authoritative and adds only the mechanical scaffolding.
Work enters as an **idea** (playbook [01 — research](00-META/process/01-research.md)) or a
**symptom** (playbook [03 — issues](00-META/process/03-issues.md)), becomes a **decision**
([02-DECISIONS](02-DECISIONS/), via playbook [02](00-META/process/02-graduation.md)), lands in a
(in the knowledge base, via playbook [02](00-META/process/02-graduation.md)), lands in a
**to-be design** naming that decision, is handed to a code repository (playbook
[04](00-META/process/04-build-handoff.md), on a feature branch per playbook
[07](00-META/process/07-feature-branches.md)) — and on shipping the as-is is updated and the
@@ -30,20 +31,22 @@ alongside `records.py`, `index.py` and `words.py` — run all four before any me
|---|---|
| What does this word mean? | [`00-META/glossary.md`](00-META/glossary.md) |
| How do I do X in this repo? | [`00-META/process/`](00-META/process/) — the playbook index is in `00-overview.md` |
| What was decided, and why? | [`02-DECISIONS/README.md`](02-DECISIONS/README.md) (reading order), then the record |
| What was decided, and why? | the knowledge base, through the mesh MCP server: `knowledge-base.ask` with the question in plain words, `knowledge-base.get` with a record's number (`reasoning: true` for the why), `knowledge-base.holds` with a topic of the reading order ([`02-DECISIONS/README.md`](02-DECISIONS/README.md)) |
| What was researched? | the knowledge base: `knowledge-base.ask`, or `knowledge-base.get` with `kind: research` and its number |
| What is being built / already runs? | [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) / [`03-DESIGN/00-as-is/`](03-DESIGN/00-as-is/) — each doc's frontmatter says its status, decisions and owning code |
| What is broken or was? | the issue tracker: `issue-tracker.list` and `issue-tracker.get` through the mesh MCP server; a design or governance issue's narrative is in [`04-ISSUES/`](04-ISSUES/) under its number |
| Which repo owns what code? | [`00-META/repos.md`](00-META/repos.md) |
| Cross-cutting status view? | the `hq-status` skill (generated, never stored) |
Statuses of research, designs and decisions live **only** in frontmatter; follow the pointers there
(`decisions:`, `code:`, `became:`) instead of reconstructing history from memory. An issue's status,
owner and fix live in the issue tracker ([ADR 0275](02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md)).
A design's status lives **only** in its frontmatter; follow the pointers there (`decisions:`, `code:`)
instead of reconstructing history from memory. A decision record's and a research effort's status and links
live in the knowledge base (ADR 0290); `knowledge-base.links` gives a record's links both ways. An issue's
status, owner and fix live in the issue tracker (ADR 0275).
## Words
One name per thing. [`00-META/glossary.md`](00-META/glossary.md) is the authority on
vocabulary, organised by the mesh's domains ([ADR 0244](02-DECISIONS/0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)):
vocabulary, organised by the mesh's domains (ADR 0244):
*controller* (not "control plane"), *foundation* (not "substrate"), *node-engine* (not "the host"), a
*node* is a machine the mesh has adopted, *seat* / *bench* / *claim*, *package* vs *artifact*. Use those
words. A retired word is named on its replacement's *Not:* line, and `00-META/checks/words.py` fails on it
@@ -52,19 +55,22 @@ in running prose; a quotation keeps its words.
## Ground rules
- **Markdown only** — but for the checks in `00-META/checks/` and `merge-check.sh` at the root, which
runs them on every pull request as its `mesh/repo-check` ([ADR 0238](02-DECISIONS/0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)).
runs them on every pull request as its `mesh/repo-check` (ADR 0238).
No new top-level folders without explicit confirmation.
- **Status lives in YAML frontmatter** — on research overviews (`status`, `became`), design
docs (`layer`, `status`, `code`, `updated`) and decision records (`status`, `date`, `deciders`).
An issue's status, owner and fix live in the issue tracker, not here: an issue report carries
- **Status lives in YAML frontmatter** — on design docs (`layer`, `status`, `code`, `updated`,
and `decisions` as "ADR NNNN"). A decision record's and a research effort's status live in the knowledge
base, and an issue's status, owner and fix in the issue tracker, not here: an issue report carries
`opened` and nothing of its status (playbook [03](00-META/process/03-issues.md)).
Never create a central status file; cross-cutting views are generated from frontmatter.
- **`02-DECISIONS/` records hold their meaning.** Supersede with a new record rather than rewriting
what was decided, the options weighed, or a consequence another record relies on. Fixing a broken
link or path is allowed, and so is a **progressive insight** — a correction of *fact* that leaves
the decision standing, made in place, marked and dated in the record's own words
([`02-DECISIONS/README.md`](02-DECISIONS/README.md)). A fact going stale is not the decision going
wrong, and superseding a sound record for one buries it.
Never create a central status file; cross-cutting views are generated when they are read.
- **No decision record or research effort is written here.** They live whole in the knowledge base and
are written with `knowledge-base.reserve` and `knowledge-base.propose` (playbooks
[01](00-META/process/01-research.md) and [02](00-META/process/02-graduation.md)); `records.py` refuses a
new path under `02-DECISIONS/` or `01-RESEARCH/`. A record is cited as "ADR NNNN" or "research NNN".
- **Decision records hold their meaning.** Supersede with a new record rather than rewriting
what was decided, the options weighed, or a consequence another record relies on. A **progressive
insight** — a correction of *fact* that leaves the decision standing — is a new version of the record,
marked and dated (playbook [02](00-META/process/02-graduation.md)). A fact going stale is not the
decision going wrong, and superseding a sound record for one buries it.
- **Design docs are prose and diagrams only** — no code. A manifest field may be named; a
manifest may not be pasted.
- **Two layers, never mixed.** [`03-DESIGN/00-as-is/`](03-DESIGN/00-as-is/) describes the mesh