From f11384c39cc722ecf47f492debc4a67d003b9169 Mon Sep 17 00:00:00 2001 From: Nils Lehnen <30603423+iderex@users.noreply.github.com> Date: Mon, 17 Aug 2026 19:25:09 +0200 Subject: [PATCH] Repair two pastes in the operator guide that no longer reproduce (#42) The exit-code section of docs/operator-guide.md quotes two runs, and neither quotation reproduced against the default branch any more. The first named a line rather than a declaration. The page said line 45: git grep -n 'ExitAskedAndDeliveredNothing = ' origin/main -- internal/hardware origin/main:internal/hardware/hardware.go:54:const ExitAskedAndDeliveredNothing = 3 The constant moved when b3ba466 held the three exit-code declarations to one contract. Nothing the sentence claims changed with it, so the quotation went stale while the claim above it stayed true, which is the failure a reader cannot tell from a claim that has gone wrong. The command loses its -n, so the paste names the file and the declaration and nothing that an unrelated edit moves. The second stopped one line into the output. The runner prints the help text after the unknown-verb line, on the same stream: ./lab frobnicate 2>&1 1>/dev/null lab: unknown verb "frobnicate" lab reads this repository and reports what it examined. lab check [path] walk the tree at path, default ".", and report lab list [path] list the experiments at path, default ".", oldest unanswered first lab help print this text lab writes nothing to the tree it reads. The page pasted the first line only, so a reader running it gets nine lines the page did not lead them to expect. It now says the help text follows, which is what the entry beside it already does. The help text stays out of the page, because a copy of it here drifts against the runner that prints it. Both were found by re-running every command the page pastes, at the current default branch, rather than by reading the page. What this does not do. It closes nothing on #42. What is open there is the download and the checksum, and this change does not reach it. Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com> --- docs/operator-guide.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/operator-guide.md b/docs/operator-guide.md index dc5acd9..6775f14 100644 --- a/docs/operator-guide.md +++ b/docs/operator-guide.md @@ -148,16 +148,27 @@ anything in the tree. Three ways to reach it, each printing to standard error: ./lab frobnicate lab: unknown verb "frobnicate" + (and then the help text, because the verb is not one it has) ./lab (the help text, because no verb was given) +The help text is described rather than pasted in both of those, because a copy +of it here drifts against the runner that prints it, and the runner is the +thing a reader is checking. + `3` is not a code this command returns. It belongs to the integration-hardware harness under `internal/hardware`, which is asked for separately, and it is declared where its only producer is: - git grep -n 'ExitAskedAndDeliveredNothing = ' -- internal/hardware - internal/hardware/hardware.go:45:const ExitAskedAndDeliveredNothing = 3 + git grep 'ExitAskedAndDeliveredNothing = ' -- internal/hardware + internal/hardware/hardware.go:const ExitAskedAndDeliveredNothing = 3 + +That command carries no line number on purpose. With `-n` the paste names a +line rather than a declaration, and an edit anywhere above the constant moves +the line without changing anything the sentence claims, so the quotation goes +stale while the claim it supports stays true. The file and the declaration are +what the claim rests on and neither of them moves. So the record fixes four codes, `lab` returns three of them, and a caller keyed on any of the four is reading that record whether or not anybody said so.