Issue 426, ADR 0290 rule 9: the decision records and research efforts leave hq for the knowledge base #312

Merged
mesh-admin merged 2 commits from feat/426-the-records-leave-hq into main 2026-10-11 11:27:12 +00:00
Contributor

Do not merge before: the knowledge base reviews proposals itself (issue 425) and issue 365 is delivered. The session that briefed this change merges it. The items under Needed outside hq before merge must land first too.

Issue 426, ADR 0290 rule 9: the knowledge base holds every decision record and research effort whole (imported at hq f08920199d, the base of this branch), so hq keeps no copy.

What this changes

  • Removed: all 278 decision records (02-DECISIONS/NNNN-*.md) and all 44 research efforts (01-RESEARCH/NNN-*/, 120 files): 398 files.
  • Rewritten (355 files): 1,534 markdown links and 7 bare paths into those folders now read "ADR NNNN" or "research NNN", with the sentence around them unchanged. Where a link's text was a bare number left over from a renumbering (such as [0050] pointing at ADR 0007), the target record is named. 533 design decisions: entries are now "ADR NNNN". The script that did this is not in the repository; the diff is the record of what it did.
  • 02-DECISIONS/README.md becomes a pointer to the knowledge base that keeps the reading order's six topic lines, unchanged in form. The knowledge base reads them (mesh-knowledge reference.go:95, LoadReference reads 02-DECISIONS/README.md through the records module) and refuses a record whose topic is not one of them, so the lines must stay. Its rules on how a record is written (progressive insight, supersession in part, the mechanism-changed note, frontmatter, body) moved to playbook 02 and are enforced by knowledge-base.propose. 01-RESEARCH/README.md becomes a one-paragraph pointer. Both folders stay, so no top-level folder is added or removed.
  • Checks: records.py keeps links and status-vs-code, and adds no-records (nothing in 02-DECISIONS/ or 01-RESEARCH/ but the two READMEs), decisions-form (a design's decisions: entries are "ADR NNNN") and mention-form (every "ADR N" in the text has 4 digits, every "research N" has 3). I made each one fail before it passed. index.py keeps the reading-order checks and drops the per-record ones and --print. cycle.py keeps the design and issue rules. words.py holds issues only, and the kept allowance is gone with research 034 and 042. sh merge-check.sh passes.
  • Playbooks 01, 02 (and 00, 04), the skills hq-new-research, hq-graduate, hq-status, hq-amend-design, hq-handoff, hq-defer and hq-sync-constitution, AGENTS.md (the "Where to look" table and the ground rules), README.md, the glossary entries for research effort and decision record, and how-we-build §change step 3 now use knowledge-base.reserve, propose, ask, get, holds, links and history, with the arguments mesh_describe gives. how-we-build.md changed, so the constitution needs a re-sync (playbook 05) after the merge.

Dropped rules, and where each lives now

Rule here until now Where it lives now
records.py rests-on (a record's extends:) knowledge base rests-on, plus the whole-set rule rests-on-live
records.py rests-on, live-citation, for hq designs nowhere yet. The reviewer checks each cited record with knowledge-base.get until designs become a knowledge-base kind (issue 428)
live-citation (records) live-citation
supersession supersedes-accepted, self-link, plus the whole-set rule supersession
partial-supersession changes-in-force, supersedes-accepted, plus the whole-set rule partial
clauses has-clause, clause-numbering, clause-lead, clause-size
numbering title, reserved
topics, index.py per-record topic topic (against the reading order kept here)
insights insight-form
cycle.py research status / became research-status, overview, became
cycle.py duplicate decision numbers reserved, plus the issue tracker's counter
cycle.py decision cited by nothing the whole-set rule cited (it reads homes given at propose and record links, and never reads hq)
cycle.py deferrals deferral
words.py on research retired-word, daemon-line

The table is also in 00-META/checks/README.md.

Needed outside hq before merge (mesh-catalog at 5668984, not changed here)

  1. records module: records_decisions must be retired or pointed at the knowledge base. modules/records/cmd/records/decisions.go:25,77-122 lists 02-DECISIONS/NNNN-*.md. After this merge it would answer six topics with no records and report success. Also main.go:54, module.json:18 and README.md:22.
  2. mesh-issues reserve. modules/mesh-issues/cmd/mesh-issues/reserve.go:31-32,51-52,122,156-170 (highestIn) reads the highest number in 02-DECISIONS and 01-RESEARCH. Because the folders stay, it reads 0 and raises nothing, so there is no warning. A counter that has not started yet would start at max(floor, reservations) and could hand out 0001. Before the merge, check that both counters have started, or set decision-floor to 293 or more and research-floor to 45 or more. Then drop the hq read (and README.md:206's description of it) or point it at the knowledge base.
  3. mesh-knowledge. reference.go:95,105 reads 02-DECISIONS/README.md, which this change keeps on purpose; it must not be removed later without moving the topics. import.go:22-23,98-114 lists the two folders: an import at a commit after this merge finds nothing. Pin the import to f08920199d or retire it. The whole-set rule cited (rules.go:474) never read hq's designs, so removing the paths does not change it. An imported record is exempt from it, and a new record must name its homes at propose.
  4. The shared instruction section writing-decision-records (claude-code module, approved 2026-10-10) tells sessions to take numbers from hq's main and branches, write supersedes-in-part: notes and run merge-check.sh for records. Replace it through claude_code_instructions_propose with "reserve and propose in the knowledge base (playbooks 01 and 02)". ADR 0290 rule 5 cites it.
  5. Mismatches found by the comparison (note 12 on issue 426). The knowledge base does not hold reconstructed, amended or research touches (14 efforts have no link for a touched record). rests-on is held only as cites (ADR 0037, 0038). The written clauses of ADR 0259, 0272, 0273, 0278 and 0288 are a list inside one ### subsection, not their decisions. 11 records with no ## Decision section have no clauses and no drafting queued. Fix these in mesh-knowledge, or accept them on the record, before the files leave.
  6. Not blocking (comments only): mesh-control internal/catalogue/port_into.go:14,16,39 links into 02-DECISIONS; mesh-catalog README.md:56-58, mesh-issues README.md:127 and mesh-lab scenarios/a-public-name.yml:3 name paths.

Left as written

04-ISSUES/ keeps 6 mentions of 02-DECISIONS/ (issues 117, 297, 354). They describe the folder and its README as they were, and issue 427 moves that content to the tracker.

Not decided here

The knowledge base has no verb that lists every record. hq-status builds the index from holds per topic and says so. A list verb, if wanted, needs its own decision.

**Do not merge before: the knowledge base reviews proposals itself (issue 425) and issue 365 is delivered.** The session that briefed this change merges it. The items under *Needed outside hq before merge* must land first too. Issue 426, ADR 0290 rule 9: the knowledge base holds every decision record and research effort whole (imported at hq f08920199d25, the base of this branch), so hq keeps no copy. ## What this changes - **Removed:** all 278 decision records (`02-DECISIONS/NNNN-*.md`) and all 44 research efforts (`01-RESEARCH/NNN-*/`, 120 files): 398 files. - **Rewritten (355 files):** 1,534 markdown links and 7 bare paths into those folders now read "ADR NNNN" or "research NNN", with the sentence around them unchanged. Where a link's text was a bare number left over from a renumbering (such as `[0050]` pointing at ADR 0007), the target record is named. 533 design `decisions:` entries are now `"ADR NNNN"`. The script that did this is not in the repository; the diff is the record of what it did. - **`02-DECISIONS/README.md`** becomes a pointer to the knowledge base that keeps **the reading order's six topic lines, unchanged in form**. The knowledge base reads them (mesh-knowledge `reference.go:95`, `LoadReference` reads `02-DECISIONS/README.md` through the records module) and refuses a record whose topic is not one of them, so the lines must stay. Its rules on how a record is written (progressive insight, supersession in part, the mechanism-changed note, frontmatter, body) moved to playbook 02 and are enforced by `knowledge-base.propose`. **`01-RESEARCH/README.md`** becomes a one-paragraph pointer. Both folders stay, so no top-level folder is added or removed. - **Checks:** `records.py` keeps `links` and `status-vs-code`, and adds `no-records` (nothing in `02-DECISIONS/` or `01-RESEARCH/` but the two READMEs), `decisions-form` (a design's `decisions:` entries are "ADR NNNN") and `mention-form` (every "ADR N" in the text has 4 digits, every "research N" has 3). I made each one fail before it passed. `index.py` keeps the reading-order checks and drops the per-record ones and `--print`. `cycle.py` keeps the design and issue rules. `words.py` holds issues only, and the `kept` allowance is gone with research 034 and 042. `sh merge-check.sh` passes. - **Playbooks 01, 02** (and 00, 04), the skills `hq-new-research`, `hq-graduate`, `hq-status`, `hq-amend-design`, `hq-handoff`, `hq-defer` and `hq-sync-constitution`, `AGENTS.md` (the "Where to look" table and the ground rules), `README.md`, the glossary entries for *research effort* and *decision record*, and `how-we-build` §change step 3 now use `knowledge-base.reserve`, `propose`, `ask`, `get`, `holds`, `links` and `history`, with the arguments `mesh_describe` gives. **`how-we-build.md` changed, so the constitution needs a re-sync (playbook 05) after the merge.** ## Dropped rules, and where each lives now | Rule here until now | Where it lives now | |---|---| | `records.py` rests-on (a record's `extends:`) | knowledge base `rests-on`, plus the whole-set rule `rests-on-live` | | `records.py` rests-on, live-citation, **for hq designs** | **nowhere yet.** The reviewer checks each cited record with `knowledge-base.get` until designs become a knowledge-base kind (issue 428) | | live-citation (records) | `live-citation` | | supersession | `supersedes-accepted`, `self-link`, plus the whole-set rule `supersession` | | partial-supersession | `changes-in-force`, `supersedes-accepted`, plus the whole-set rule `partial` | | clauses | `has-clause`, `clause-numbering`, `clause-lead`, `clause-size` | | numbering | `title`, `reserved` | | topics, index.py per-record topic | `topic` (against the reading order kept here) | | insights | `insight-form` | | cycle.py research status / became | `research-status`, `overview`, `became` | | cycle.py duplicate decision numbers | `reserved`, plus the issue tracker's counter | | cycle.py decision cited by nothing | the whole-set rule `cited` (it reads `homes` given at propose and record links, and never reads hq) | | cycle.py deferrals | `deferral` | | words.py on research | `retired-word`, `daemon-line` | The table is also in `00-META/checks/README.md`. ## Needed outside hq before merge (mesh-catalog at 5668984, not changed here) 1. **records module: `records_decisions` must be retired or pointed at the knowledge base.** `modules/records/cmd/records/decisions.go:25,77-122` lists `02-DECISIONS/NNNN-*.md`. After this merge it would answer six topics with no records and report success. Also `main.go:54`, `module.json:18` and `README.md:22`. 2. **mesh-issues `reserve`.** `modules/mesh-issues/cmd/mesh-issues/reserve.go:31-32,51-52,122,156-170` (`highestIn`) reads the highest number in `02-DECISIONS` and `01-RESEARCH`. Because the folders stay, it reads 0 and raises nothing, so there is no warning. A counter that has not started yet would start at max(floor, reservations) and could hand out 0001. Before the merge, check that both counters have started, or set `decision-floor` to 293 or more and `research-floor` to 45 or more. Then drop the hq read (and `README.md:206`'s description of it) or point it at the knowledge base. 3. **mesh-knowledge.** `reference.go:95,105` reads `02-DECISIONS/README.md`, which this change keeps on purpose; it must not be removed later without moving the topics. `import.go:22-23,98-114` lists the two folders: an import at a commit after this merge finds nothing. Pin the import to f08920199d25 or retire it. The whole-set rule `cited` (`rules.go:474`) never read hq's designs, so removing the paths does not change it. An imported record is exempt from it, and a new record must name its `homes` at propose. 4. **The shared instruction section *writing-decision-records*** (claude-code module, approved 2026-10-10) tells sessions to take numbers from hq's `main` and branches, write `supersedes-in-part:` notes and run `merge-check.sh` for records. Replace it through `claude_code_instructions_propose` with "reserve and propose in the knowledge base (playbooks 01 and 02)". ADR 0290 rule 5 cites it. 5. **Mismatches found by the comparison** (note 12 on issue 426). The knowledge base does not hold `reconstructed`, `amended` or research `touches` (14 efforts have no link for a touched record). `rests-on` is held only as `cites` (ADR 0037, 0038). The written clauses of ADR 0259, 0272, 0273, 0278 and 0288 are a list inside one `###` subsection, not their decisions. 11 records with no `## Decision` section have no clauses and no drafting queued. Fix these in mesh-knowledge, or accept them on the record, before the files leave. 6. **Not blocking (comments only):** mesh-control `internal/catalogue/port_into.go:14,16,39` links into `02-DECISIONS`; mesh-catalog `README.md:56-58`, mesh-issues `README.md:127` and mesh-lab `scenarios/a-public-name.yml:3` name paths. ## Left as written `04-ISSUES/` keeps 6 mentions of `02-DECISIONS/` (issues 117, 297, 354). They describe the folder and its README as they were, and issue 427 moves that content to the tracker. ## Not decided here The knowledge base has no verb that lists every record. `hq-status` builds the index from `holds` per topic and says so. A `list` verb, if wanted, needs its own decision.
Author
Contributor

Delivery novox/hq@0afc8cc5f81c — delivered since 2026-10-11T11:27:43Z

Delivery plan — builds nothing: the change touches no module of the mesh's graph

Transitions

  • 2026-10-11 11:25 (new) → proposed (announced): novox/hq#312's head announced
  • 2026-10-11 11:26 proposed → checked (checked): the verdict names this commit
  • 2026-10-11 11:26 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
  • 2026-10-11 11:27 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
  • 2026-10-11 11:27 published → delivered (done): nothing for a walk to move

The commit's note under refs/notes/mesh-plan keeps every transition: git log --notes=mesh-plan.

<!-- mesh-delivery:view --> **Delivery** `novox/hq@0afc8cc5f81c` — **delivered** since 2026-10-11T11:27:43Z **Delivery plan** — builds nothing: the change touches no module of the mesh's graph **Transitions** - 2026-10-11 11:25 (new) → proposed (announced): novox/hq#312's head announced - 2026-10-11 11:26 proposed → checked (checked): the verdict names this commit - 2026-10-11 11:26 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-11 11:27 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-11 11:27 published → delivered (done): nothing for a walk to move The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.
jschoubben added 1 commit 2026-10-11 10:56:13 +00:00
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
418261213c
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.
jschoubben force-pushed feat/426-the-records-leave-hq from 6d57991d04 to 418261213c 2026-10-11 10:56:13 +00:00 Compare
jschoubben added 1 commit 2026-10-11 11:25:23 +00:00
Name the commit the knowledge base's records now come from, and link research with touches and decisions with rests-on (review of #312)
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 delivered
0afc8cc5f8
mesh-admin merged commit 22ffe073bf into main 2026-10-11 11:27:12 +00:00
mesh-admin deleted branch feat/426-the-records-leave-hq 2026-10-11 11:27:12 +00:00
Sign in to join this conversation.
No Reviewers
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novox/hq#312