From 32382c03ed2b6388bf4c35a78fa84213100f7520 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Sat, 29 Aug 2026 12:11:16 +0200 Subject: [PATCH 1/2] Point the two checklist links at the file that holds them `docs/promotion.md` wrote both of its decision-record links relative to the repository root rather than to the file carrying them, so each resolved to a path under `docs/docs/` and neither opened. The label keeps the full path and the target is now relative to `docs/`, which is how the nine links in `docs/operator-guide.md` and `docs/privacy.md` are written and why all of theirs resolve. The failure it prevents is a reader who follows the checklist to the record that fixes what a promotion section may not restate and lands on nothing, at the moment the document sends them away for the answer. Both sites point at exactly those records. grep -rn '](docs/' docs/ --include=*.md exit=1 Refs #218 Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- docs/promotion.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/promotion.md b/docs/promotion.md index 2473cb0..737b0d8 100644 --- a/docs/promotion.md +++ b/docs/promotion.md @@ -7,7 +7,7 @@ archaeology. This is the list somebody works through before the hand-over. What the record then says is fixed by -[docs/decisions/0005-how-a-result-leaves.md](docs/decisions/0005-how-a-result-leaves.md), +[docs/decisions/0005-how-a-result-leaves.md](decisions/0005-how-a-result-leaves.md), which this document does not restate. Work through the list, then write the section that record describes. @@ -36,7 +36,7 @@ The licence the code carries out. [LICENSE](../LICENSE) at the root of this board is the GNU General Public License version 3, so that is what the code carries out and the receiving side inherits terms rather than finding none. This repository declares the same licence to the checks that read one, and -[docs/decisions/0018-the-licence-of-this-board.md](docs/decisions/0018-the-licence-of-this-board.md) +[docs/decisions/0018-the-licence-of-this-board.md](decisions/0018-the-licence-of-this-board.md) is the answer both of them come from. The contributor's consent, where the receiving board's terms differ from that From 36eddf59e199659baa2cf6a6eec2731da697a338 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Sat, 29 Aug 2026 12:14:59 +0200 Subject: [PATCH 2/2] Record the route a landed record's stale evidence takes Two landed records carry pastes that have stopped reproducing, and record 0000 gives a landed record exactly one legal edit, the line naming what superseded it. Which route repairs the rest was written nowhere, so every reader who met one resolved it their own way and the ones who resolved it by editing left nothing behind saying so. The route: a landed record's evidence is never brought up to date, because a paste is a measurement of its date rather than a claim about today. Where the decision still stands on today's evidence, nothing happens. Where the premise fell, the answer is a successor record carrying the fresh measurement, never an edit. The failure it prevents is a forged reading. An edited paste asserts a run that never happened, in the file a later reader trusts most, and afterwards a record whose premise fell and one whose premise held read identically. Records 0012 and 0018 are read against that test in the record's second section, both stand on today's evidence, and neither is touched. Every paste in the new record reproduced at 55ef1616e1da8889c005fb7f185fae613557e839. go run ./cmd/lab check . 27 decision records read 0 refused The means is a decision record in docs/decisions/, because this is a rule later work depends on and CONTRIBUTING.md sends such a rule there; nothing else in this tree holds one, and record 0000 already fixes the shape it has to take. Refs #216 Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- ...-landed-record-that-stopped-reproducing.md | 154 ++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 docs/decisions/0026-evidence-in-a-landed-record-that-stopped-reproducing.md diff --git a/docs/decisions/0026-evidence-in-a-landed-record-that-stopped-reproducing.md b/docs/decisions/0026-evidence-in-a-landed-record-that-stopped-reproducing.md new file mode 100644 index 0000000..9e91dfe --- /dev/null +++ b/docs/decisions/0026-evidence-in-a-landed-record-that-stopped-reproducing.md @@ -0,0 +1,154 @@ +# 0026. Evidence in a landed record that has stopped reproducing + +## What was decided + +A landed record's evidence is never brought up to date. A paste in a record is +a measurement of the day it was taken rather than a claim about today, and +editing it into agreement with a later reading forges a run nobody made. Record +`0000` gives a landed record exactly one legal edit, the line naming what +superseded it, and that edit stays exactly as narrow as it is. + +When a paste in a landed record stops reproducing, one of two things is true, +and which one it is decides everything that follows. + +Either the decision still stands on today's evidence, and then nothing happens. +A stale paste under a standing decision is history, not error. It says what was +in front of whoever took the decision, which is what a later reader needs in +order to judge the reasoning rather than only the outcome. No edit, no +annotation, no successor record. + +Or the ground moved far enough that the decision would fall differently today, +and the answer there is not an edit either. It is a new record superseding the +old one, carrying the fresh measurement and naming what it replaces, with the +earlier record left word-stable as the reason things were once otherwise. That +route is already record `0000`'s, and what this record adds is that a fallen +premise is one of the things that sends a decision down it. + +So the question a paste that no longer reproduces raises is about the decision +and not about the paste. Does this still hold is the whole test. Does this +still print what it printed is not the test, and answering the second one is +how five documents in this tree came to describe an answered question as open. + +**What a reader is owed here and does not get.** Nothing marks a paste that has +stopped reproducing, and under this decision nothing ever will, so a reader who +needs to know whether a quoted command still answers that way runs it. Carrying +the command is what makes that possible and is why these records carry commands +at all. The cost is real and lands on the reader in a hurry, who takes a paste +for a current reading: the two records this route was decided against are both +cases where a reader following the paste is told something that was true on the +day it was taken and is not true now. That price is named here rather than met +later, and it is what a directory whose records can be trusted not to have +moved under anybody costs. + +**Nothing refuses either half of this.** No check reads whether a paste still +reproduces, and none could without running commands out of a document, which is +the opposite of the property record `0009` fixes about what an automatic run +executes. Nothing notices a decision whose premise has fallen and whose +successor nobody wrote either. Both halves rest on whoever reads a record and +whoever reads the change, and that is written here so that this record is not +mistaken for a gate. + +## What it applies to + +Every record in `docs/decisions/`, the ones already landed included, because +what it governs is what may be done to a record after it lands rather than how +one is written. + +It applies to a paste, a quoted command output, a linked issue state and any +other reading a record carries as evidence. It does not apply to what a record +decided, which is record `0000`'s subject, and it opens no second route to +changing that. + +It does not apply to a typo fixed before anything depends on the record, which +record `0000` already calls ordinary. + +It does not apply to documents outside `docs/decisions/`. A document describing +how this repository works is meant to describe it today, so a claim in one that +has stopped reproducing is a defect to repair in place. That is the difference +this record rests on: `docs/promotion.md` was repaired and record `0012` is not +going to be. + +Two records were read against the test above on 2026-08-29, and both are +standing decisions on today's evidence, so neither is edited and neither gains +a successor. + +`docs/decisions/0012-the-supported-platforms.md` says that whether this board +publishes downloadable release artefacts is open, and makes itself superseded +if the answer is source only. The answer is not source only, so the conditional +never fires and the six platforms stand: + + gh issue view 46 --repo Flowfin/lab --json state --jq '.state' + CLOSED + +`docs/decisions/0018-the-licence-of-this-board.md` says the file on the default +branch says something else, that this repository declares nothing, and that a +reader should trust neither the record nor the sidebar until issue #47 lands. +That issue landed, and the three readings now agree with what the record +decided: + + gh api repos/Flowfin/lab --jq '.license.spdx_id' + GPL-3.0 + gh issue view 47 --repo Flowfin/lab --json state --jq '.state' + CLOSED + git grep -n 'const DeclaredLicence' origin/main \ + -- internal/invariants/invariants.go + origin/main:internal/invariants/invariants.go:92:const DeclaredLicence = "GNU GENERAL PUBLIC LICENSE" + +Those pastes are measurements of 2026-08-29 and this record is subject to its +own rule about them. + +## What else was considered + +Editing the stale paste in place and leaving the decision alone. + +Widening record `0000`'s single legal edit to admit an evidence-only amendment +appended to a landed record. + +Superseding whenever a paste stops reproducing, whether or not the decision +moved. + +Marking a stale paste with a line saying it no longer reproduces. + +Deciding nothing, and leaving each case to whoever meets it. + +## What each rejected option would have cost + +Editing the paste in place costs the record the only thing that makes it worth +quoting. A paste is presented as the output of a command run at a moment, so an +edited one asserts a run that never happened, in the file a later reader trusts +most. It also destroys the evidence that the ground moved at all: after the +edit, a record whose premise fell and one whose premise held read identically. +It is the edit record `0000` refuses, arriving under a name that sounds like +maintenance. + +An evidence-only amendment costs the one-legal-edit rule its edge, and it costs +it at once rather than gradually. An amendment to the evidence and an amendment +to the argument are the same shape in a diff, so the rule stops being readable +off the file and becomes a judgement about what the editor meant. It also +creates an obligation with no owner: an amendment is itself a reading of a day, +so a record accumulating them accumulates stale ones, and the option solves its +own problem once and then reproduces it. + +Superseding on every stale paste costs the directory its signal. A superseding +record means the ground moved, and a chain of them over records whose decisions +never changed leaves a reader unable to tell which supersession changed +anything. It also grows without limit and for reasons outside this board: a +closed issue, an edited ruleset or a renamed constant elsewhere would each owe +a record here, and the number of them would say nothing about how often this +repository changed its mind. + +Marking the paste is the status field record `0000` already rejected, in a +different costume. It is a line that has to be kept true by somebody +remembering, on a file the rules say may not be edited, so it needs the +amendment option above before it can exist at all and then inherits every cost +of it. A marker nobody maintains is worse than no marker, because a record +carrying one unmarked stale paste and one marked one reads as though the +unmarked one is current. + +Deciding nothing costs what was already measured. Five documents on this board +described an answered question as open, one of them long enough that a +checklist refused a hand-over the answer permits, and the whole set was found +by somebody running the commands rather than by anything noticing. Without a +written route each of those meets a different reader who resolves it a +different way, and the ones who resolve it by editing leave nothing behind +saying they did.