From 510f7aecf1b2058e67aacee13e27a229981f764c Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 12:29:32 +0200 Subject: [PATCH 1/4] To-be 55: the rests-on and touches links and the import's refresh; ADR 0248's index now comes from the knowledge base --- ...index-is-generated-when-it-is-read-and-never-stored.md | 6 ++++++ ...d-lives-whole-in-the-knowledge-base-made-of-clauses.md | 2 +- 03-DESIGN/01-to-be/55-the-knowledge-base.md | 8 ++++++++ 3 files changed, 15 insertions(+), 1 deletion(-) diff --git a/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md b/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md index 82988c42..3d6728a9 100644 --- a/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md +++ b/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md @@ -10,6 +10,12 @@ supersedes-in-part: # 248. The decision index is generated when it is read, and never stored +> **The mechanism changed — 2026-10-11, by [ADR 0290](0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md).** +> What still stands: the index is generated when it is read and never stored, in the reading order of the topics. +> What moved: it is generated by the knowledge base (`knowledge-base.holds` per topic, `ask`, `get`) from the records +> it holds, not by the records module from this repository's files; the records module's `records_decisions` is +> retired and names those verbs (issue 488). + ## Context [ADR 0019](0019-how-this-repository-works.md) says two things about the decision index. Every diff --git a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md index 32cf55a7..40fe9345 100644 --- a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md +++ b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md @@ -112,7 +112,7 @@ rule 8 already decided that the issue tracker hands out decision and research nu ([ADR 0126](0126-a-module-declares-its-own-seats.md)). Its first kinds are the **decision record** and the **research effort**. 2. **The knowledge base is the truth for a record whole**: its number, kind, title, topic, status, date, deciders, its - typed links (held in both directions), its clauses, and its reasoning (context, options weighed, consequences, + typed links (held in both directions; to-be 55 §2 lists their kinds), its clauses, and its reasoning (context, options weighed, consequences, how it is checked; a research effort's documents). **Every version is kept**, with who wrote it and when, and any two versions can be compared. Once the import has run and been checked, no record is written in this repository. 3. **A decision record is made of clauses.** A clause is one numbered statement of what was decided, with a status: diff --git a/03-DESIGN/01-to-be/55-the-knowledge-base.md b/03-DESIGN/01-to-be/55-the-knowledge-base.md index 283c4523..2b679fe1 100644 --- a/03-DESIGN/01-to-be/55-the-knowledge-base.md +++ b/03-DESIGN/01-to-be/55-the-knowledge-base.md @@ -69,6 +69,8 @@ the records module, as the issue tracker's import does. | `changes` | a clause or a record → a clause it replaces part of | | `extends` | a record → a record it builds on | | `became` | a research effort → a decision record or design | +| `rests-on` | a record → a record its decision rests on | +| `touches` | a research effort → a record or area it bears on (a record by link, an area as text) | | `cites` | any record → any record or issue it names | ## 3. Clauses @@ -153,6 +155,12 @@ whole, at its own number, as its first version, naming the commit. It creates wh advances a counter; a second run changes nothing and says so. Records written in this repository after the import, while the first slice does not take writes yet, are taken in by running it again. +**Refresh.** `import` with `refresh` re-reads, at the commit given, every record whose only versions were written by +the import, and writes the corrected record as a new version naming why; a record anyone else wrote a version of is +never touched. It repairs what an earlier import misread (issue 487) and is idempotent: a second run changes +nothing. `dry-run` lists what it would change. Once this repository holds no records, `import` refuses rather than +reporting nothing created (issue 488). + Before the records leave this repository (issue 426), every record is compared with its file at the import's commit, field by field and section by section, and the result is written on issue 426. From d2de5ddf8c92ca327c86de7cf6e85d5d26b05330 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 12:30:39 +0200 Subject: [PATCH 2/4] To-be 55 and ADR 0248: say exactly what the links and refresh do, and why the index moved --- ...index-is-generated-when-it-is-read-and-never-stored.md | 8 ++++---- 03-DESIGN/01-to-be/55-the-knowledge-base.md | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md b/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md index 3d6728a9..dedbc9db 100644 --- a/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md +++ b/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md @@ -11,10 +11,10 @@ supersedes-in-part: # 248. The decision index is generated when it is read, and never stored > **The mechanism changed — 2026-10-11, by [ADR 0290](0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md).** -> What still stands: the index is generated when it is read and never stored, in the reading order of the topics. -> What moved: it is generated by the knowledge base (`knowledge-base.holds` per topic, `ask`, `get`) from the records -> it holds, not by the records module from this repository's files; the records module's `records_decisions` is -> retired and names those verbs (issue 488). +> What still stands: what is decided is answered when it is asked, and no list of records is stored. What moved: the +> records left this repository's files for the knowledge base (ADR 0290), so the records module, which reads only +> files, can no longer answer it; the knowledge base does, through `holds` (a topic's clauses in force), `ask` and +> `get`. The records module's `records_decisions` is retired and names those verbs (issue 488). ## Context diff --git a/03-DESIGN/01-to-be/55-the-knowledge-base.md b/03-DESIGN/01-to-be/55-the-knowledge-base.md index 2b679fe1..43252d95 100644 --- a/03-DESIGN/01-to-be/55-the-knowledge-base.md +++ b/03-DESIGN/01-to-be/55-the-knowledge-base.md @@ -69,8 +69,8 @@ the records module, as the issue tracker's import does. | `changes` | a clause or a record → a clause it replaces part of | | `extends` | a record → a record it builds on | | `became` | a research effort → a decision record or design | -| `rests-on` | a record → a record its decision rests on | -| `touches` | a research effort → a record or area it bears on (a record by link, an area as text) | +| `rests-on` | a decision → a decision it stands on | +| `touches` | a research effort → a record, issue or design it bears on (by link), or an area (as text) | | `cites` | any record → any record or issue it names | ## 3. Clauses @@ -155,8 +155,8 @@ whole, at its own number, as its first version, naming the commit. It creates wh advances a counter; a second run changes nothing and says so. Records written in this repository after the import, while the first slice does not take writes yet, are taken in by running it again. -**Refresh.** `import` with `refresh` re-reads, at the commit given, every record whose only versions were written by -the import, and writes the corrected record as a new version naming why; a record anyone else wrote a version of is +**Refresh.** `import` with `refresh` re-reads, at the commit given, every record whose versions were all written by +the import or a refresh, with nothing waiting over it, and writes the corrected record as a new version naming why; a record anyone else wrote a version of is never touched. It repairs what an earlier import misread (issue 487) and is idempotent: a second run changes nothing. `dry-run` lists what it would change. Once this repository holds no records, `import` refuses rather than reporting nothing created (issue 488). From 4ea4cf6529ad4aee53f51eef0b31bf68f593784c Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 12:38:04 +0200 Subject: [PATCH 3/4] ADR 0290 rule 8 and to-be 55: a refresh repairs drafted records too, as a new version --- ...d-lives-whole-in-the-knowledge-base-made-of-clauses.md | 8 +++++++- 03-DESIGN/01-to-be/55-the-knowledge-base.md | 6 ++++-- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md index 40fe9345..897985df 100644 --- a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md +++ b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md @@ -25,6 +25,10 @@ extends: 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists- > inference layer. Following that, the knowledge base now reviews a proposal itself, through a fresh judgement. Option 3 of > *How a record is reviewed*, rule 4, rule 6 and the consequences say so. + +> **Updated — 2026-10-11.** Rule 8 gains `refresh`: comparing every imported record with its file found fields the +> first import did not hold and clauses read from the wrong list (issue 487). A refresh writes a new version and +> overwrites nothing, so the rule's *never overwrites* stands. ## Context [Research 045](../01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md) measured, on 2026-10-11, how an @@ -150,7 +154,9 @@ rule 8 already decided that the issue tracker hands out decision and research nu ([ADR 0041](0041-events-are-a-relationship.md)), carrying what changed and who changed it. 8. **The import reads this repository at a commit and can run again.** It writes every decision record and research effort whole, at its own number, with the commit as its first version's source; it creates what is absent, never - overwrites, never advances a counter, and a second run changes nothing and says so. A record whose clauses are + overwrites, never advances a counter, and a second run changes nothing and says so. With `refresh` it re-reads a + record nobody but the import and the knowledge base's own drafting has written, and writes what an earlier import + misread as a new version naming why (to-be 55 §8). A record whose clauses are written as numbered statements gets them as `written`. A prose record gets them `drafted` by the agent's judgement ([ADR 0278](0278-the-issue-tracker-checks-every-new-issue-for-a-duplicate-through-a-judgement-the-agent-makes-without-tools.md)), then `confirmed` by a second judgement that sees only the record and the drafts; the operator is told per topic and diff --git a/03-DESIGN/01-to-be/55-the-knowledge-base.md b/03-DESIGN/01-to-be/55-the-knowledge-base.md index 43252d95..ebc4bd11 100644 --- a/03-DESIGN/01-to-be/55-the-knowledge-base.md +++ b/03-DESIGN/01-to-be/55-the-knowledge-base.md @@ -156,8 +156,10 @@ advances a counter; a second run changes nothing and says so. Records written in while the first slice does not take writes yet, are taken in by running it again. **Refresh.** `import` with `refresh` re-reads, at the commit given, every record whose versions were all written by -the import or a refresh, with nothing waiting over it, and writes the corrected record as a new version naming why; a record anyone else wrote a version of is -never touched. It repairs what an earlier import misread (issue 487) and is idempotent: a second run changes +the import, a refresh, or the knowledge base's own drafting and confirming of clauses, with nothing waiting over +it, and writes the corrected record as a new version naming why; a record anyone else wrote a version of is +never touched. Clauses already drafted and confirmed are kept when the Decision section's text is unchanged, and +drafted again when it changed. It repairs what an earlier import misread (issue 487) and is idempotent: a second run changes nothing. `dry-run` lists what it would change. Once this repository holds no records, `import` refuses rather than reporting nothing created (issue 488). From cd8b4c5e5ded21e3324b4305593859bf0c56d352 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 12:38:49 +0200 Subject: [PATCH 4/4] ADR 0290: say on whose word rule 8 gained refresh, and name the same versions as to-be 55 --- ...d-lives-whole-in-the-knowledge-base-made-of-clauses.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md index 897985df..f50e8fc6 100644 --- a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md +++ b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md @@ -25,10 +25,11 @@ extends: 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists- > inference layer. Following that, the knowledge base now reviews a proposal itself, through a fresh judgement. Option 3 of > *How a record is reviewed*, rule 4, rule 6 and the consequences say so. - -> **Updated — 2026-10-11.** Rule 8 gains `refresh`: comparing every imported record with its file found fields the +> **Updated — 2026-10-11, by the session building the knowledge base, under the operator's word to finish it.** Rule 8 +> gains `refresh`: comparing every imported record with its file found fields the > first import did not hold and clauses read from the wrong list (issue 487). A refresh writes a new version and > overwrites nothing, so the rule's *never overwrites* stands. + ## Context [Research 045](../01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md) measured, on 2026-10-11, how an @@ -155,7 +156,8 @@ rule 8 already decided that the issue tracker hands out decision and research nu 8. **The import reads this repository at a commit and can run again.** It writes every decision record and research effort whole, at its own number, with the commit as its first version's source; it creates what is absent, never overwrites, never advances a counter, and a second run changes nothing and says so. With `refresh` it re-reads a - record nobody but the import and the knowledge base's own drafting has written, and writes what an earlier import + record whose versions were all written by the import, a refresh, or the knowledge base's own drafting and + confirming of clauses, and writes what an earlier import misread as a new version naming why (to-be 55 §8). A record whose clauses are written as numbered statements gets them as `written`. A prose record gets them `drafted` by the agent's judgement ([ADR 0278](0278-the-issue-tracker-checks-every-new-issue-for-a-duplicate-through-a-judgement-the-agent-makes-without-tools.md)),