Merge pull request 'to-be 55: a drafted clause may be changed, and a clause another record links keeps its number (issue 494, ADR 0321)' (#329) from design/55-a-drafted-clause-may-be-changed into main

03-DESIGN/01-to-be/55-the-knowledge-base.md

@@ -5,6 +5,7 @@ code: []
 updated: 2026-10-12
 decisions:
   - "ADR 0290"
+  - "ADR 0321"
 ---
 
 # 55 — The knowledge base
@@ -157,6 +158,14 @@ per clause whether the record says exactly that; an accepted clause becomes `con
 same way. When every record of a topic has been through both, the operator is told once per topic, with the counts
 confirmed and still drafted. `return` with a record's number and a reason sends it back to be drafted again.
 
+**A drafted clause may be changed, and a linked clause keeps its number** (ADR 0321, issue 494). A later record's
+`changes` may name a drafted clause, confirmed or not, as it may one in force or changed; only a superseded or proposed
+clause is refused. On that record's acceptance the drafted clause is marked `changed`, naming the clause that changed
+it, keeps its number and stays `drafted`: it is still never served as in force, and `get` and `ask` say both. Because
+a redraft numbers a record's clauses anew, `return` refuses a record any of whose clauses another record changed or
+links by number, in a version served or proposed, naming each such link; a record that changes the drafted clause is
+the way to correct it. A record no other record links by clause is returned as before.
+
 ## 8. The import
 
 `import` takes a commit of this repository (and `dry-run`) and writes every decision record and research effort
@@ -198,6 +207,7 @@ repository keeps no copy of the records, generated or otherwise (issue 435, answ
 | Every version is kept and comparable | the module's test: three versions, `history` lists them, the difference of the first and third is exact |
 | The import changes nothing on a second run, and loses nothing | the module's test over a fixture repository; and the comparison of § 8 on issue 426 |
 | A drafted clause is never served as in force | the module's test: `holds` over a record with only drafted clauses answers none, and `ask` marks them |
+| A drafted clause may be changed, and a linked clause is never renumbered | the module's tests: a record changing a drafted clause is accepted, and the clause is then `changed`, keeps its number, stays drafted and is not served; `return` of a record whose clause another record changed or links by number is refused naming the link, and writes nothing |
 | An answer stays within its bound | the module's test over the full import of `main` at a recorded commit: every `ask`, `get` and `holds` of a fixed question list |
 | A record written in this repository meanwhile writes its clauses | `records.py`, check `clauses`, on every hq pull request, until the records left this repository (issue 426); since then `records.py`, check `no-records`, refuses any record written here |
 | Live | the acceptance sentence, asked from a session outside this repository |