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
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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user