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
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)
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.
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.
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.
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.
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.
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.
Deliverynovox/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`.
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…
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.
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…
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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
02-DECISIONS/NNNN-*.md) and all 44 research efforts (01-RESEARCH/NNN-*/, 120 files): 398 files.[0050]pointing at ADR 0007), the target record is named. 533 designdecisions: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.mdbecomes a pointer to the knowledge base that keeps the reading order's six topic lines, unchanged in form. The knowledge base reads them (mesh-knowledgereference.go:95,LoadReferencereads02-DECISIONS/README.mdthrough 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 byknowledge-base.propose.01-RESEARCH/README.mdbecomes a one-paragraph pointer. Both folders stay, so no top-level folder is added or removed.records.pykeepslinksandstatus-vs-code, and addsno-records(nothing in02-DECISIONS/or01-RESEARCH/but the two READMEs),decisions-form(a design'sdecisions:entries are "ADR NNNN") andmention-form(every "ADR N" in the text has 4 digits, every "research N" has 3). I made each one fail before it passed.index.pykeeps the reading-order checks and drops the per-record ones and--print.cycle.pykeeps the design and issue rules.words.pyholds issues only, and thekeptallowance is gone with research 034 and 042.sh merge-check.shpasses.hq-new-research,hq-graduate,hq-status,hq-amend-design,hq-handoff,hq-deferandhq-sync-constitution,AGENTS.md(the "Where to look" table and the ground rules),README.md, the glossary entries for research effort and decision record, andhow-we-build§change step 3 now useknowledge-base.reserve,propose,ask,get,holds,linksandhistory, with the argumentsmesh_describegives.how-we-build.mdchanged, so the constitution needs a re-sync (playbook 05) after the merge.Dropped rules, and where each lives now
records.pyrests-on (a record'sextends:)rests-on, plus the whole-set rulerests-on-liverecords.pyrests-on, live-citation, for hq designsknowledge-base.getuntil designs become a knowledge-base kind (issue 428)live-citationsupersedes-accepted,self-link, plus the whole-set rulesupersessionchanges-in-force,supersedes-accepted, plus the whole-set rulepartialhas-clause,clause-numbering,clause-lead,clause-sizetitle,reservedtopic(against the reading order kept here)insight-formresearch-status,overview,becamereserved, plus the issue tracker's countercited(it readshomesgiven at propose and record links, and never reads hq)deferralretired-word,daemon-lineThe table is also in
00-META/checks/README.md.Needed outside hq before merge (mesh-catalog at 5668984, not changed here)
records_decisionsmust be retired or pointed at the knowledge base.modules/records/cmd/records/decisions.go:25,77-122lists02-DECISIONS/NNNN-*.md. After this merge it would answer six topics with no records and report success. Alsomain.go:54,module.json:18andREADME.md:22.reserve.modules/mesh-issues/cmd/mesh-issues/reserve.go:31-32,51-52,122,156-170(highestIn) reads the highest number in02-DECISIONSand01-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 setdecision-floorto 293 or more andresearch-floorto 45 or more. Then drop the hq read (andREADME.md:206's description of it) or point it at the knowledge base.reference.go:95,105reads02-DECISIONS/README.md, which this change keeps on purpose; it must not be removed later without moving the topics.import.go:22-23,98-114lists the two folders: an import at a commit after this merge finds nothing. Pin the import tof08920199dor retire it. The whole-set rulecited(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 itshomesat propose.mainand branches, writesupersedes-in-part:notes and runmerge-check.shfor records. Replace it throughclaude_code_instructions_proposewith "reserve and propose in the knowledge base (playbooks 01 and 02)". ADR 0290 rule 5 cites it.reconstructed,amendedor researchtouches(14 efforts have no link for a touched record).rests-onis held only ascites(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## Decisionsection have no clauses and no drafting queued. Fix these in mesh-knowledge, or accept them on the record, before the files leave.internal/catalogue/port_into.go:14,16,39links into02-DECISIONS; mesh-catalogREADME.md:56-58, mesh-issuesREADME.md:127and mesh-labscenarios/a-public-name.yml:3name paths.Left as written
04-ISSUES/keeps 6 mentions of02-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-statusbuilds the index fromholdsper topic and says so. Alistverb, if wanted, needs its own decision.Delivery
novox/hq@0afc8cc5f81c— delivered since 2026-10-11T11:27:43ZDelivery plan — builds nothing: the change touches no module of the mesh's graph
Transitions
The commit's note under
refs/notes/mesh-plankeeps every transition:git log --notes=mesh-plan.6d57991d04to418261213c