From 510f7aecf1b2058e67aacee13e27a229981f764c Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 12:29:32 +0200 Subject: [PATCH] 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.