Skip to content

Repair two pastes in the operator guide that no longer reproduce (#42) - #147

Merged
iderex merged 1 commit into
mainfrom
documents/two-pastes-in-the-guide-no-longer-reproduce
Aug 17, 2026
Merged

Repair two pastes in the operator guide that no longer reproduce (#42)#147
iderex merged 1 commit into
mainfrom
documents/two-pastes-in-the-guide-no-longer-reproduce

Conversation

@iderex

@iderex iderex commented Aug 17, 2026

Copy link
Copy Markdown
Contributor

Refs #42

What this changes

Two quotations in the exit-code section of docs/operator-guide.md. Both are
pastes of what a command printed, and neither of them reproduced any more.

The first is where exit code 3 is declared. The page pasted a git grep -n
line naming internal/hardware/hardware.go:45, and the constant sits on line
54 today. It moved when b3ba466 held the three exit-code declarations to one
contract, which changed nothing that the sentence around the paste claims, so
the quotation went stale while the claim above it stayed true. The command
loses its -n, so the paste names the file and the declaration rather than a
line that an unrelated edit moves.

The second is ./lab frobnicate. The runner prints the unknown-verb line and
then the help text, on the same stream, and the page pasted the first line
only. It now says the help text follows. The help text itself stays out of the
page, because a copy of it here drifts against the runner that prints it, and
the entry beside it in the same block already describes it rather than pasting
it.

What failure it prevents

Somebody checking the page against the runner finds a paste that disagrees with
what the command gives them, and nothing on the page separates that from the
page being wrong about the thing it is explaining. The first of the two had
already reached that state. The second was a line short of the output from the
day it was written.

What was run

At f11384c, from a checkout of this branch.

git grep -n 'ExitAskedAndDeliveredNothing = ' origin/main -- internal/hardware
origin/main:internal/hardware/hardware.go:54:const ExitAskedAndDeliveredNothing = 3

git log --oneline -1 origin/main -- internal/hardware/hardware.go
b3ba466 Hold the three exit-code declarations to one contract (#125)

go build -o lab ./cmd/lab
./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.

go build ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...
gofmt -l cmd internal
(no output from any of the three)

go test -count=1 -v ./cmd/... ./internal/... 2>&1 | grep -cE '^--- PASS'
119
go test -count=1 -v ./cmd/... ./internal/... 2>&1 | grep -cE '^--- (FAIL|SKIP)'
0

go run ./cmd/lab check .
examined .
1 experiment directory walked, 1 record read
18 decision records read
the time this run read is 2026-08-17T17:24:43Z
0 refused

The integration-hardware harness was not asked for and nothing in it ran, which
is what the suite's own disclosure line says about that run.

What this does not do

It does not finish #42. What is open there is the download and the checksum
paragraphs, and those need something published to download.

That sentence used to be spelled with the word this platform reads as a closing
keyword, followed by the reference, and the merge shut the issue on it. The
issue is open again and its done-condition did not move. The negation is
invisible to whatever parses the body, so the word is gone from it rather than
qualified.

It does not sweep the rest of the tree. The same class is live one document
over: docs/supply-chain.md cites .github/workflows/zizmor.yml:63 and
:82, and both of those lines are now :72 and :91. That file is outside
what this change is about and nothing here touches it.

It reads two quotations rather than every claim on the page. The counts in the
first-run and listing sections were re-derived and still hold at the commit
they name, and the three exit-2 routes were re-run and all three do print to
standard error, but nothing here re-argues what the page says.

This change has had no second reader.

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>
@iderex
iderex merged commit 432c8d0 into main Aug 17, 2026
25 of 26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant