Merge pull request 'To-be 55: rests-on and touches links, the import's refresh; ADR 0248's index comes from the knowledge base' (#314) from design/55-links-and-refresh into main

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: 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
 
 [ADR 0019](0019-how-this-repository-works.md) says two things about the decision index. Every

02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md

@@ -25,6 +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, 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
@@ -112,7 +117,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:
@@ -150,7 +155,10 @@ 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 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)),
    then `confirmed` by a second judgement that sees only the record and the drafts; the operator is told per topic and

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 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
@@ -153,6 +155,14 @@ 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 versions were all written by
+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).
+
 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.