Skip to content

Write down the route a landed record's stale evidence takes, and point two checklist links at the file that holds them - #219

Merged
iderex merged 2 commits into
mainfrom
docs/the-route-for-stale-evidence-and-two-links-that-do-not-resolve
Aug 29, 2026
Merged

Write down the route a landed record's stale evidence takes, and point two checklist links at the file that holds them#219
iderex merged 2 commits into
mainfrom
docs/the-route-for-stale-evidence-and-two-links-that-do-not-resolve

Conversation

@iderex

@iderex iderex commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Two document-only changes on one branch. Both land text and nothing else, so
they share a pull request rather than moving the mainline under each other for
no reason. They are separate commits and separate topics.

#218, the two links that resolve to nothing

docs/promotion.md wrote both of its decision-record links relative to the
repository root rather than to the file that holds 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.

The done-condition asks that grep -rn '](docs/' docs/ --include=*.md return
nothing. At 36eddf59e199659baa2cf6a6eec2731da697a338:

grep -rn '](docs/' docs/ --include=*.md
exit=1

And every link in that file resolves from the directory that holds it:

grep -oE '\]\([^)#][^)]*\)' docs/promotion.md | sed 's/^](//; s/)$//' |
  while read -r l; do (cd docs && test -e "$l" && echo "ok   $l" || echo "MISS $l"); done
ok   decisions/0005-how-a-result-leaves.md
ok   ../LICENSE
ok   decisions/0018-the-licence-of-this-board.md
ok   decisions/0020-consent-to-promote-under-other-terms.md
ok   decisions/0013-how-the-record-format-changes.md

#216, the route a landed record's stale evidence takes

What was left of that issue was the route by which a landed record carrying
evidence that no longer reproduces is repaired, written down, and both sites
left in whatever state the route says. The route was decided on the issue and
lived only there, so this adds
docs/decisions/0026-evidence-in-a-landed-record-that-stopped-reproducing.md:
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.

Records 0012 and 0018 are read against that test in the record's second
section, and both stand on today's evidence, so neither is edited and neither
gains a successor. 0012 makes itself superseded only if entry four of issue
#46 answered source only, and record 0021 decides that this board publishes
signed downloadable artefacts, so that conditional cannot fire. 0018 decides
GPL-3.0 and the three readings it said disagreed now agree with it.

Every paste in the new record was reproduced before it was written, at
55ef1616e1da8889c005fb7f185fae613557e839:

gh issue view 46 --repo Flowfin/lab --json state --jq '.state'
CLOSED
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"

One clause of that issue's original done-condition is deliberately not met, and
it is the clause the route overturned. It asks that git grep -n 'issue #46'
return no site asserting an entry is open, and one site still does:

git grep -n 'issue #46' -- . | cut -d: -f1,2
docs/decisions/0001-the-runner-is-written-in-go.md:70
docs/decisions/0005-how-a-result-leaves.md:53
docs/decisions/0012-the-supported-platforms.md:78
docs/quality-parity.md:654

The first two are each about their own record's scope and the issue body puts
them outside its scope; the fourth says the entry is answered. The third is the
one, and under the route above it stays. That clause was written before the
route existed, and the issue's own later statement of what is left replaces it:
the route is decided and written down, and both sites are left in whatever
state the route says.

The means

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, record 0000 already fixes the shape it has to take, and the
existing checks read that directory, so the artefact is judged by the suites
that already exist rather than by a parallel apparatus.

What I ran

go build ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...
gofmt -l cmd internal
go run ./cmd/lab check .
go test -count=1 ./cmd/... ./internal/...

gofmt -l printed nothing. The checker printed:

examined .
1 experiment directory walked, 1 record read
27 decision records read
0 refused

Every package in the suite reported ok.

What this does not carry

No second reader tonight. Nobody but me has read these two commits, and the
evidence above stands in place of that reading rather than alongside it. Both
changes are text: one moves four link characters, the other adds a file that
nothing imports and no run executes.

Nothing here re-scores the board and neither change claims a re-score. The
record's own second section is a reading taken on 2026-08-29 and is subject to
the rule the record states about pastes.

Closes #216
Closes #218

iderex added 2 commits August 29, 2026 12:11
`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>
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 55ef161.

    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>
@iderex iderex added documentation Improvements or additions to documentation bug Something isn't working labels Aug 29, 2026
@iderex iderex self-assigned this Aug 29, 2026
@iderex iderex added this to the 2. Repository scaffolding milestone Aug 29, 2026
@iderex
iderex merged commit 9208ceb into main Aug 29, 2026
25 checks passed
@iderex
iderex deleted the docs/the-route-for-stale-evidence-and-two-links-that-do-not-resolve branch August 29, 2026 10:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working documentation Improvements or additions to documentation

Projects

None yet

1 participant