Skip to content

Date a reading that has gone false instead of deleting the paragraph under it - #502

Merged
iderex merged 2 commits into
mainfrom
records/0313-a-dated-re-reading
Sep 18, 2026
Merged

iderex merged 2 commits into
mainfrom
records/0313-a-dated-re-reading

Conversation

@iderex

@iderex iderex commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

The issue this belongs to

Closes #313
Closes #397
Closes #394

Three issues, one branch and one pull request, because all three land documents
in one register and the record the other two need is in this change. Four more
issues are open on sites of the same class - #361, #366, #367 and #380 - and
none of them is touched here.

What changed

docs/decisions/0313-a-dated-re-reading-of-a-landed-record.md records the
decision of 2026-09-18: a landed record whose pasted output or whose sentence
about a reading has stopped being true may gain one dated note, opening
Read again on YYYY-MM-DD: directly under the reading it concerns, saying what
the command answers now, at which reference or in which checkout it has to be
run, or how the sentence beside it is to be read. Nothing else in the record
moves. An output that never reproduced at any commit of the record is deleted
under that note; an output standing as the reference the record's other readings
were taken at is left alone, with no note; a record is superseded only where what
it decided changes.

It narrows 0001 on the rule that a record is never edited in place, and 0001
carries the pointer back. It does not narrow 0269: taking a case a record priced
is going further on that case rather than narrowing a clause, which is the
distinction 0267 draws and which 0291 already followed on this board.

Three sites take the note it prescribes.

No ordinal is written into any of it. 0001 permits three edits that are not
supersessions and 0269 named itself a fourth, so a number written here would go
stale the next time a record narrows that rule, and the record hands the reader
the command instead.

What failure it prevents

A record that is wrong in one line stays wrong. Before this, the moves available
at a stale reading were a deletion that breaks the paragraph beside it and an
edit to prose that 0001 withholds, so the repair cost a supersession and nobody
supersedes a record to repair a paste. This has already happened rather than
being expected: seven issues are open on seven such sites in this one register,
the oldest since 2026-09-07, and each ends in the same rule question rather than
in a change.

What each of the three sites hands a reader today is an answer the command beside
it does not produce, so a reader who runs it cannot tell whether the record is
wrong or they are.

The second commit is a correction of the first. The population command written
into 0313 answered seven where three notes exist, because the record carries the
marker literal in the sentences that declare and price it, and the reversal
condition rested on the same number. Both commands now exclude that record by
path. It was found by running the command as it was written.

Evidence

Everything below is run at the commit being pushed.

git rev-parse HEAD
a055abe9c72f409b28416b05b8c8b1b8297aa1f6

0091's reading, which is #313's site. The record pastes AGPL-3.0 and the
sentence beside it points at 0303:

gh api repos/Flowfin/core --jq '.license.spdx_id'
Apache-2.0

Neither the pasted output nor the answer the sentence points at.

0269's window, which is #397's site. At the mainline it frames no name and no
part of the paragraph the sentence describes:

git show origin/main:docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md | sed -n '137,140p'

git grep -l '#103' -- docs/decisions

## A dependency a record already standing requires

The reading the note pins it to:

git show d200143^:docs/decisions/0103-what-admits-a-dependency-and-what-is-refused.md | sed -n '135,142p'
The three refusals with a worked case behind them are all quotable. 0061 refuses a
tracing library, and 0112 refuses a cross-platform media framework on size on
every target:

    git grep -l '#103' -- docs/decisions
    docs/decisions/0041-how-a-cache-key-is-built.md
    docs/decisions/0061-the-span-facility.md
    docs/decisions/0112-where-the-platform-decoder-begins.md

0243's ten readings, which is #394's site. The count the note is written
over, at this commit:

git grep -nE "^ {4,}(grep|sed|awk|ls|comm|cat|wc|head|tail) .*(^| )(README\.md|Cargo\.toml|src/|src/lib\.rs)" HEAD -- docs/ README.md SECURITY.md NOTICE.md CONTRIBUTING.md CODE_OF_CONDUCT.md | wc -l
10

The notes this change adds, counted with the declaring record excluded:

git grep -h 'Read again on ' HEAD -- docs/decisions/ ':!docs/decisions/0313-a-dated-re-reading-of-a-landed-record.md' | wc -l
3

git grep -h 'Read again on ' HEAD -- docs/decisions/ | wc -l
7

The second number is the one the first commit rested on, and it is the reason for
the second commit.

The two checks whose subject this change is, and the invariant loader beside
them:

bash .github/decision-records/decision-records.sh check
Records: 67. Fields found: 8.
ok    8 field(s) name a record that exists, name a clause, and are named back
Every narrowing these records declare is named from both ends.

bash .github/doc-paths/doc-paths.sh check
ok    79 document(s), 395 named path(s) resolved, 0 excused as examples
Every path these documents name resolves against the tracked set.

bash .github/invariants/invariants.sh check
Every rule above was applied to its subject and refused nothing.

The paths this change touches, against the scope the three issues declare:

git diff --name-only origin/main...HEAD
docs/decisions/0001-decision-records.md
docs/decisions/0091-what-the-first-release-contains.md
docs/decisions/0243-the-means-a-certificate-is-validated-with.md
docs/decisions/0269-a-reading-a-record-pasted-that-has-moved.md
docs/decisions/0313-a-dated-re-reading-of-a-landed-record.md
docs/decisions/README.md

What this does not cover

Nothing in this tree refuses a note that departs from the shape. The check over
docs/decisions/ reads the Narrows: and Narrowed-by: fields and nothing
else, and says so on its own output. Whether a note is true, whether it is placed
under the right reading, and whether a second one has been added under one
reading are judgements no reading of the tree makes, and the review is where a
wrong one is caught. That is stated in the record rather than only here.

A note goes stale exactly as the paste under it did. What this buys is that the
staleness is dated, and nothing here makes any of the three sites correct
forever.

Four of the seven sites the decision names are untouched: #361, #366, #367 and
#380. Each needs its own reading of its own record, and none is prejudged by the
note shape landing here.

0243's note says the ten readings were taken inside the extracted source of the
crate the paragraph above each one names. That is read off the record's own
neighbouring commands, which name their crate by a directory in front of the
path, and off the prose above each of the ten. I did not fetch any of those
crates and did not re-run one there, so which checkout each of the ten belongs to
is not measured here. #394 carries what this tree answers for each of them.

0091's first done-condition asks that the record no longer carry an output that
does not reproduce. Under the move decided on 2026-09-18 it still carries it,
with the note dating it, because the sentence beside the paste reasons from the
output and deleting it would leave that sentence naming nothing. The decision
says in its own words that each of the seven sites closes with the note it
prescribes, and that is the ground this closes on rather than the wording of the
bullet.

No guard is added or edited here, so there is no refusal to watch fail. This
change is documents only: no source file, no workflow and no script is touched,
and the suite and the compile legs judge bytes none of it moved.

Who has read it

Nobody other than me. There was no second reader available for it, and the
evidence above stands in place of one.

…under it

0269 repairs a stale paste by deleting the output and leaving the command. At
three kinds of site that costs the paragraph rather than the paste: a sentence
added beside the paste reasons from the output, the command names a path the
tree no longer carries, or the paste never reproduced at any commit the record
has had. Seven issues on this board are open on sites of those kinds, and each
of them ends in the same rule question, so a record that is wrong in one line
stays wrong because the only authorised repair is a supersession nobody takes
for a reading.

0313 records the decision of 2026-09-18: a landed record may gain one dated
note, opening `Read again on YYYY-MM-DD:` under the reading it concerns, saying
what the command answers now, at which reference or in which checkout it has to
be run, or how the sentence beside it is to be read. Nothing else in the record
moves. An output that never reproduced is deleted under that note; an output
standing as the reference the record's other readings were taken at is left
alone; a record is superseded only where what it decided changes. It narrows
0001 on the rule that a record is never edited in place, and 0001 names it back.

Three sites take the note it prescribes. 0091's licence paste keeps its output
and its sentence and gains the answer that listing gives today, `Apache-2.0`,
which is neither the pasted one nor the one the sentence points at. 0269's own
instance window is pinned to `d200143^` with the line numbers that frame the
three names there, because the commit that added 0269 is the commit that deleted
them from 0103, so that window returned one name before the change and none
after it. 0243 says once, above its ten readings that name a file with no
directory in front of it, that each was taken inside the extracted source of the
crate the paragraph above it names and none of them in this tree.

No ordinal is written into any of it. 0001 permits three edits that are not
supersessions and 0269 named itself a fourth, so a number written here would
move the next time a record narrows that rule.

Closes #313
Closes #397
Closes #394

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
The population command in 0313 answered seven where three notes exist. The
record carries the literal `Read again on ` in the sentences that declare and
price it and in the command itself, so the grep counted its own declaration
alongside the notes, and the reversal condition rested on the same number. Both
commands now exclude this record by path, and the sentence above the first one
says why. Found by running the command as it was written:

    git grep -h 'Read again on ' HEAD -- docs/decisions/ | wc -l
    7
    git grep -h 'Read again on ' HEAD -- docs/decisions/ ':!docs/decisions/0313-a-dated-re-reading-of-a-landed-record.md' | wc -l
    3

Contributes to #313

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment