Skip to content

Restore the operator-guide pastes that reproduce (#155) - #159

Merged
iderex merged 1 commit into
mainfrom
docs/the-operator-guide-pastes-that-stopped-reproducing
Aug 21, 2026
Merged

Restore the operator-guide pastes that reproduce (#155)#159
iderex merged 1 commit into
mainfrom
docs/the-operator-guide-pastes-that-stopped-reproducing

Conversation

@iderex

@iderex iderex commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Refs #155

What this changes

docs/operator-guide.md, back to the bytes the default branch held at
90656ba77a7c930d04d2205b2dd99df787853a92:

git rev-parse 90656ba:docs/operator-guide.md
6775f1473b6af20969eb75003d6bc96854e0aca7
git hash-object docs/operator-guide.md
6775f1473b6af20969eb75003d6bc96854e0aca7

Two pastes in that file had been repaired once and the repair is what came off.

How the absence arrived

d3edfc95b8526033c79cb26afe48282c2c090e32 took its tree from an older state of
the default branch and landed on top of a newer one, under a message describing
a change to how one workflow pin is commented. This file was among the seven
paths it replaced, and it is the only commit to have touched it since, so
nothing arrived afterwards that taking the whole blob would drop:

git log --format='%H %s' 90656ba..origin/main -- docs/operator-guide.md
d3edfc95b8526033c79cb26afe48282c2c090e32 Name the version the pinned commit actually is (#151)

What failure it prevents

An operator reading a quotation in the guide that no longer reproduces, and
concluding the runner rather than the document has moved.

The first paste is the one that has already gone stale, which makes this
measurable rather than argued. The document on the default branch quotes a
git grep -n and pastes line 45. Run today it prints 54:

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

Nothing about the constant changed. An edit above it moved the line, which is
exactly what the removed paragraph says will happen, and why the command it
restores carries no -n. That form still reproduces:

git grep 'ExitAskedAndDeliveredNothing = ' -- internal/hardware
internal/hardware/hardware.go:const ExitAskedAndDeliveredNothing = 3

The second is the unknown-verb example, cut off after its one error line. The
runner prints the help text after that line:

go run ./cmd/lab frobnicate
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.
exit status 2

The restored line describes that text rather than pasting it, and the restored
paragraph gives the reason: a copy of the help text in this document drifts
against the runner that prints it, and the runner is the thing a reader is
checking.

Nothing in this tree refuses either drift. lab check reads records and
decision records, not the prose of this guide, so what stands behind these two
pastes is the repair and the reason written beside it. That is a disclosure, not
a mechanism.

What was run

At 9f0c6b3ca30cf4154e58de8ba72c9fa3b11431f7, on Windows, with no graphical
session and as an ordinary user:

go build ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...
gofmt -l cmd internal
go test -count=1 ./cmd/... ./internal/...
ok  	github.com/Flowfin/lab/cmd/contexts	0.449s
ok  	github.com/Flowfin/lab/cmd/lab	2.805s
ok  	github.com/Flowfin/lab/cmd/notices	10.895s
ok  	github.com/Flowfin/lab/cmd/pullrequest	0.702s
ok  	github.com/Flowfin/lab/internal/check	0.957s
ok  	github.com/Flowfin/lab/internal/contexts	0.409s
ok  	github.com/Flowfin/lab/internal/hardware	0.710s
ok  	github.com/Flowfin/lab/internal/invariants	0.736s
ok  	github.com/Flowfin/lab/internal/notices	0.406s
ok  	github.com/Flowfin/lab/internal/prose	0.727s
ok  	github.com/Flowfin/lab/internal/pullrequest	0.713s

go build, go vet and gofmt -l each printed nothing, which is the passing
result for all three.

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-21T14:03:24Z
0 refused

The suite does not read this document, so a green run here says nothing broke
rather than that the pastes are right. The two commands above are what say that.

No test was skipped for needing elevation, and none was run with any.

What this does not do

It does not finish #155. Two path groups that commit removed are still missing:
LICENSE with the ## License section of README.md, and two sections of
docs/quality-parity.md.

It does not touch the second question #155 raises, which is whether anything
here should refuse a merge that removes a tracked path without saying so in its
body.

It does not move #42. What that issue landed is this file; what was missing is a
repair to two of its quotations.

No second person has read this change. The evidence above stands in place of
one, and that is a disclosure rather than an assurance.

This does not finish #155. Two more of the path groups that commit removed are
still missing.

What was wrong. `d3edfc95b8526033c79cb26afe48282c2c090e32` took its tree from an
older state of the default branch and landed on top of a newer one, under a
message describing a change to how one workflow pin is commented.
`docs/operator-guide.md` was among the seven paths it replaced, and it is the
only commit to have touched that file since, so the file went back to a form
whose two pastes had already been repaired.

Both are back to the repaired form, and the repair is a rule-one repair rather
than a preference. The exit-code paragraph quoted a `git grep -n`, and the line
number in that paste is now wrong while the claim it supports is still true:

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

The document on the default branch pastes that same command with `45`. Nothing
about the constant changed; an edit above it moved the line, which is exactly
what the removed paragraph says happens and why the command it restores carries
no `-n`:

    git grep 'ExitAskedAndDeliveredNothing = ' -- internal/hardware
    internal/hardware/hardware.go:const ExitAskedAndDeliveredNothing = 3

The unknown-verb example is the second. It had been cut off after the one error
line, and the runner prints the help text after it:

    go run ./cmd/lab frobnicate
    lab: unknown verb "frobnicate"

    lab reads this repository and reports what it examined.
    ...
    exit status 2

The restored line describes that text rather than pasting it, for the reason
the restored paragraph gives: a copy of the help text in this document drifts
against the runner that prints it, and the runner is what a reader is checking.

What failure this prevents is an operator reading a quotation that no longer
reproduces and concluding the tree, rather than the document, has moved.

The blob is the bytes that were there rather than a retyping of them:

    git rev-parse 90656ba:docs/operator-guide.md
    6775f14
    git hash-object docs/operator-guide.md
    6775f14

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex
iderex merged commit 8cf9031 into main Aug 21, 2026
25 checks passed
@iderex
iderex deleted the docs/the-operator-guide-pastes-that-stopped-reproducing branch August 21, 2026 14:10
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