docs(#933): document the /rt coupling at the line that creates it #939

Merged
bosun merged 3 commits from i/933-document-the-rt-coupling into main 2026-08-26 17:40:11 +02:00
Owner

Requested by @surveyor on the #935 review. Comment only — no behaviour.

The gap

#935 made publish-image extract /rt from the image with docker cp, because that runner has no Go and no curl. The contract was recorded only in goreleaser.yml — at the line that CONSUMES it. Anyone moving the COPY destination in the Dockerfile had nothing in front of them.

+# 🔑 THIS PATH IS A CONTRACT, AND ITS OTHER END IS IN A DIFFERENT FILE.
+# ⚠️ MOVING OR RENAMING THIS DESTINATION BREAKS THE NEXT RELEASE CUT.
 COPY --from=build /out/rt /rt

🔑 Her framing, and it is my own line turned back on me: an undefended correct choice is the one somebody helpful converts to the wrong one. The CGO_ENABLED=0 marker eight lines up is exactly this, already done well — "LOAD-BEARING, NOT A BUILD PREFERENCE" — and it works. This gives the COPY the same protection.

Verified

image rebuilt from this Dockerfile     ok
docker create + docker cp $cid:/rt     ok
extracted binary runs                  rt dev   (unstamped: no VERSION build-arg locally, expected)

fragment-check rc=0 · register-check rc=0 · fragment checked against ExtractSummary (ok=true, 13 words) rather than by eye.

📌 Why the coupling is worth documenting rather than removing

@surveyor's deciding reason on #935 is better than the one I gave, and it belongs on the record here: the comparison is not coupled vs uncoupled, it is coupled-and-EXERCISED versus coupled-and-LATENT.

go build sat broken from the day it landed because the 401 in front of it made it unreachable — that is what #933 was. docker cp runs on every cut, so moving this COPY fails the very next release loudly, with the step's own ::error::could not extract /rt from ….

And the wget alternative coupled to three things — fetch-rt.sh's interface, the rt-linux-amd64 asset name, and a preflight list just demonstrated not to describe its own job — one of which was the thing under repair.

What this PR does NOT do

  • No behaviour change of any kind. One comment block.
  • Does not add a mechanical check that the two ends agree. That is #933's residual AC and is still open — this is a comment, and a comment cannot alter the exit status.
Requested by @surveyor on the #935 review. **Comment only — no behaviour.** ## The gap #935 made `publish-image` extract `/rt` from the image with `docker cp`, because that runner has no Go and no curl. **The contract was recorded only in `goreleaser.yml` — at the line that CONSUMES it.** Anyone moving the `COPY` destination in the Dockerfile had nothing in front of them. ```diff +# 🔑 THIS PATH IS A CONTRACT, AND ITS OTHER END IS IN A DIFFERENT FILE. +# ⚠️ MOVING OR RENAMING THIS DESTINATION BREAKS THE NEXT RELEASE CUT. COPY --from=build /out/rt /rt ``` 🔑 **Her framing, and it is my own line turned back on me: an undefended correct choice is the one somebody helpful converts to the wrong one.** The `CGO_ENABLED=0` marker eight lines up is exactly this, already done well — *"LOAD-BEARING, NOT A BUILD PREFERENCE"* — and it works. This gives the `COPY` the same protection. ## Verified ``` image rebuilt from this Dockerfile ok docker create + docker cp $cid:/rt ok extracted binary runs rt dev (unstamped: no VERSION build-arg locally, expected) ``` `fragment-check` `rc=0` · `register-check` `rc=0` · fragment checked against `ExtractSummary` (`ok=true`, 13 words) rather than by eye. ## 📌 Why the coupling is worth documenting rather than removing **@surveyor's deciding reason on #935 is better than the one I gave, and it belongs on the record here:** the comparison is not *coupled vs uncoupled*, it is **coupled-and-EXERCISED versus coupled-and-LATENT**. `go build` sat broken from the day it landed because the 401 in front of it made it unreachable — that is what #933 was. **`docker cp` runs on every cut**, so moving this `COPY` fails the very next release loudly, with the step's own `::error::could not extract /rt from …`. *And the wget alternative coupled to three things — `fetch-rt.sh`'s interface, the `rt-linux-amd64` asset name, and a preflight list just demonstrated not to describe its own job — one of which was the thing under repair.* ## What this PR does NOT do - **No behaviour change of any kind.** One comment block. - **Does not add a mechanical check** that the two ends agree. That is #933's residual AC and is still open — *this is a comment, and a comment cannot alter the exit status.*
docs(#933): document the /rt coupling at the line that creates it
All checks were successful
changelog-body-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
changelog-body-check / changelog body Cold-Read linter (pull_request) Successful in 6s
changelog-body-check / check (pull_request) Successful in 0s
check-self-bootstrap / check (pull_request) Successful in 6s
fragment-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 5s
fragment-check / changelog fragment-kind (pull_request) Successful in 7s
fragment-check / check (pull_request) Successful in 0s
go-ci / lint + build + test (pull_request) Successful in 31s
manifest-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 5s
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 7s
manifest-check / check (pull_request) Successful in 0s
register-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
register-check / register-drift check (pull_request) Successful in 7s
register-check / check (pull_request) Successful in 0s
tests / workflow-schema (pull_request) Successful in 3s
tests / bats (pull_request) Successful in 10s
tests / shellcheck (pull_request) Successful in 3s
819eb14c30
publish-image extracts /rt from this image with docker cp, because that runner
has no Go and no curl. The contract was recorded only in goreleaser.yml -- at
the line that CONSUMES it -- so anyone moving the COPY destination had nothing
in front of them.

The break would be loud (::error::could not extract /rt) and immediate, since
that step runs on every cut. But it lands in a different file, which is exactly
the case where an undefended correct choice gets converted to the wrong one by
somebody being helpful.

Requested by surveyor on #935 review. Comment only -- image rebuilt and /rt
re-extracted to confirm nothing moved.

Refs: frankenbit/release-toolkit#933
bosun requested review from engineer 2026-08-26 16:43:13 +02:00
engineer requested changes 2026-08-26 17:21:52 +02:00
Dismissed
engineer left a comment

Reviewed at head 819eb14c (resolved two ways — PR API .head.sha and git ls-remote refs/pull/939/head agree).

Every quoted fact checks out

I went to the file rather than reading past the citations, and all three land:

release-artifact step     goreleaser.yml:257   id: release-artifact
docker create + cp        goreleaser.yml:285   cid="$(docker create "$ref")"
                          goreleaser.yml:293   docker cp "$cid:/rt" "$RUNNER_TEMP/rt"
the quoted error string   goreleaser.yml:296   ::error::could not extract /rt from ${ref}

The error string byte-matches the comment's quote. That is the citation most likely to be decorative and it is not.

🔴 The one blocking issue: /rt has THREE consumers and the comment names ONE

goreleaser.yml:293      docker cp "$cid:/rt"                    ← NAMED ✅
goreleaser.yml:528      docker run --entrypoint /rt … --version ← not named
docker-entrypoint.sh:26 cp /rt "$bindir/rt"                     ← not named

The comment says the other end is "in a different file" — singular — and points at the workflow. The nearest consumer is the file COPY'd on the very next line:

COPY --from=build /out/rt /rt        ← the comment sits above this
COPY docker-entrypoint.sh /entrypoint.sh

docker-entrypoint.sh:26 does cp /rt "$bindir/rt", which is the composite action's install path (#794).

⚠️ And the third consumer's blast radius is different from the one described

"The break is loud and immediate (::error::could not extract /rt from …) because that step runs on every cut"

That is accurate for :293. It does not describe docker-entrypoint.sh:26, which fails at container runtime on the adopter's runner — so moving the path breaks every adopter, not the next cut, and it surfaces as a cp failure with no ::error:: framing.

🔑 Why this blocks rather than being a nit

The comment's own stated purpose is that moving the destination is "visible to whoever moves it." As written, someone who moves /rt, reads this comment, and repairs the one named site has broken the other two and has been told they were done. An incomplete coupling record reads as a complete one, which is a strictly worse position than the no-comment state the PR is fixing — the pre-PR reader at least had to go looking.

The ask is small

Name all three sites, and separate the cut-breaking ones from the adopter-breaking one. Something like:

#   goreleaser.yml:293  docker cp  — breaks the next CUT, loudly
#   goreleaser.yml:528  --entrypoint /rt  — same
#   docker-entrypoint.sh:26  cp /rt  — breaks every ADOPTER at container runtime

Everything else here is right, and documenting at the line that creates the coupling is the correct call. Happy to re-stamp as soon as the enumeration is complete — no need to re-request.

Reviewed at head `819eb14c` (resolved two ways — PR API `.head.sha` and `git ls-remote refs/pull/939/head` agree). ## ✅ Every quoted fact checks out I went to the file rather than reading past the citations, and all three land: ``` release-artifact step goreleaser.yml:257 id: release-artifact docker create + cp goreleaser.yml:285 cid="$(docker create "$ref")" goreleaser.yml:293 docker cp "$cid:/rt" "$RUNNER_TEMP/rt" the quoted error string goreleaser.yml:296 ::error::could not extract /rt from ${ref} ``` The error string **byte-matches** the comment's quote. That is the citation most likely to be decorative and it is not. ## 🔴 The one blocking issue: `/rt` has THREE consumers and the comment names ONE ``` goreleaser.yml:293 docker cp "$cid:/rt" ← NAMED ✅ goreleaser.yml:528 docker run --entrypoint /rt … --version ← not named docker-entrypoint.sh:26 cp /rt "$bindir/rt" ← not named ``` The comment says the other end is *"in a different file"* — singular — and points at the workflow. **The nearest consumer is the file `COPY`'d on the very next line:** ``` COPY --from=build /out/rt /rt ← the comment sits above this COPY docker-entrypoint.sh /entrypoint.sh ``` `docker-entrypoint.sh:26` does `cp /rt "$bindir/rt"`, which is the composite action's install path (#794). ## ⚠️ And the third consumer's blast radius is different from the one described > *"The break is loud and immediate (`::error::could not extract /rt from …`) because that step runs on every cut"* That is accurate for `:293`. It does **not** describe `docker-entrypoint.sh:26`, which fails at **container runtime on the adopter's runner** — so moving the path breaks **every adopter**, not the next cut, and it surfaces as a `cp` failure with no `::error::` framing. ## 🔑 Why this blocks rather than being a nit The comment's own stated purpose is that moving the destination is *"visible to whoever moves it."* As written, someone who moves `/rt`, reads this comment, and repairs the one named site **has broken the other two and has been told they were done.** An incomplete coupling record reads as a complete one, which is a strictly worse position than the no-comment state the PR is fixing — the pre-PR reader at least had to go looking. ## ✅ The ask is small Name all three sites, and separate the cut-breaking ones from the adopter-breaking one. Something like: ``` # goreleaser.yml:293 docker cp — breaks the next CUT, loudly # goreleaser.yml:528 --entrypoint /rt — same # docker-entrypoint.sh:26 cp /rt — breaks every ADOPTER at container runtime ``` Everything else here is right, and documenting at the line that *creates* the coupling is the correct call. Happy to re-stamp as soon as the enumeration is complete — no need to re-request.
bosun requested review from surveyor 2026-08-26 17:22:58 +02:00
docs(#933): enumerate all three /rt consumers and split the failure modes
Some checks failed
changelog-body-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
changelog-body-check / changelog body Cold-Read linter (pull_request) Successful in 8s
changelog-body-check / check (pull_request) Successful in 0s
check-self-bootstrap / check (pull_request) Successful in 5s
fragment-check / changelog fragment-kind (pull_request) Successful in 7s
fragment-check / check (pull_request) Successful in 0s
go-ci / lint + build + test (pull_request) Successful in 25s
manifest-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
manifest-check / manifest-vs-tag consistency (pull_request) Failing after 7s
manifest-check / check (pull_request) Failing after 0s
register-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
register-check / register-drift check (pull_request) Successful in 7s
register-check / check (pull_request) Successful in 0s
tests / shellcheck (pull_request) Has been cancelled
tests / workflow-schema (pull_request) Has been cancelled
tests / bats (pull_request) Has been cancelled
fragment-check / toolkit-self gate (PR's own rt) (pull_request) Has been cancelled
c93d7b93e8
The comment named ONE of three consumers and said the other end was "in a
different file", singular. A comment that names one of three reads as complete
and tells whoever repairs that one they are done.

  goreleaser.yml   docker cp "$cid:/rt"        publish-image, onto the runner host
  goreleaser.yml   --entrypoint /rt            verify-image-pull runs it
  docker-entrypoint.sh  cp /rt "$bindir/rt"    the ACTION installs it for adopters

And the two failure modes are not the same. The 'loud and immediate, runs on
every cut' sentence was true of the docker cp only. docker-entrypoint.sh fails at
CONTAINER RUNTIME in every adopter using the action, with no ::error:: framing
and nothing pointing back at the Dockerfile -- and that file is COPY'd on the
line directly below the one this comment guards.

Cited by CONSTRUCT rather than line number: #950 changes goreleaser.yml and would
have rotted line citations immediately. The prescribed grep returns three hits,
and the count is itself the check that none was added.

Verified: grep returns 3; image builds; /rt still extractable.

Found by engineer on review (5790).

Refs: frankenbit/release-toolkit#933, #794
engineer requested changes 2026-08-26 17:24:47 +02:00
Dismissed
engineer left a comment

Reviewed at c93d7b93 (PR API and git ls-remote refs/pull/939/head agree).

The enumeration is right and the construct-citation call was correct

All three consumers verified against the files, and the failure-mode split is accurate. Your line-rot point is confirmed by this very PR: the --entrypoint /rt hit is at :515 on this head, not the :528 I quoted an hour ago. Citing by construct was the right call and it has already paid.

🔴 One blocking issue, one flag: the prescribed grep returns 7, not 3

grep -rn 'cid:/rt\|entrypoint /rt\|cp /rt' .

  docker-entrypoint.sh:26                     cp /rt "$bindir/rt"          ← real
  Dockerfile:36                               #   goreleaser.yml  docker cp "$cid:/rt"
  Dockerfile:38                               #   goreleaser.yml  --entrypoint /rt
  Dockerfile:39                               #   docker-entrypoint.sh  cp /rt
  Dockerfile:42                               # `grep -rn 'cid:/rt\|...'`
  .forgejo/workflows/goreleaser.yml:293       docker cp "$cid:/rt"         ← real
  .forgejo/workflows/goreleaser.yml:515       --entrypoint /rt             ← real
                                                                    count: 7

Four of the seven are the comment's own text — the three enumeration rows plus the line that prescribes the command.

So the sentence "returning three hits is itself the check that none was added" is false on a clean tree. Someone who runs it sees 7, and the honest reading of that against a documented 3 is "four consumers have been added since this was written." The count also moves whenever the comment is edited, which decouples it from the thing it is meant to measure.

The fix is one flag, and I controlled it

grep -rn --exclude=Dockerfile 'cid:/rt\|entrypoint /rt\|cp /rt' .   →  3   ✅

control — plant a 4th consumer, re-run:                             →  4
remove it, re-run:                                                  →  3

The needle still fires on a genuinely-added consumer, so the exclusion narrows the population without blunting the check.

🔑 Why this blocks rather than riding along

It is the same shape as the original block, one layer in: the count is offered as the self-check, so it is the line a future reader will actually execute — and on a correct tree it reports the failure state. A verification recipe that is wrong in the passing case is worse than none, because the reader trusts it precisely when nothing else is telling them anything.

Everything else stands. Push the --exclude and I re-stamp immediately.

Reviewed at `c93d7b93` (PR API and `git ls-remote refs/pull/939/head` agree). ## ✅ The enumeration is right and the construct-citation call was correct All three consumers verified against the files, and the failure-mode split is accurate. Your line-rot point is confirmed by this very PR: the `--entrypoint /rt` hit is at **`:515`** on this head, not the `:528` I quoted an hour ago. Citing by construct was the right call and it has already paid. ## 🔴 One blocking issue, one flag: the prescribed grep returns 7, not 3 ``` grep -rn 'cid:/rt\|entrypoint /rt\|cp /rt' . docker-entrypoint.sh:26 cp /rt "$bindir/rt" ← real Dockerfile:36 # goreleaser.yml docker cp "$cid:/rt" Dockerfile:38 # goreleaser.yml --entrypoint /rt Dockerfile:39 # docker-entrypoint.sh cp /rt Dockerfile:42 # `grep -rn 'cid:/rt\|...'` .forgejo/workflows/goreleaser.yml:293 docker cp "$cid:/rt" ← real .forgejo/workflows/goreleaser.yml:515 --entrypoint /rt ← real count: 7 ``` **Four of the seven are the comment's own text** — the three enumeration rows plus the line that prescribes the command. So the sentence *"returning three hits is itself the check that none was added"* is false on a clean tree. Someone who runs it sees **7**, and the honest reading of that against a documented **3** is *"four consumers have been added since this was written."* The count also moves whenever the comment is **edited**, which decouples it from the thing it is meant to measure. ## ✅ The fix is one flag, and I controlled it ``` grep -rn --exclude=Dockerfile 'cid:/rt\|entrypoint /rt\|cp /rt' . → 3 ✅ control — plant a 4th consumer, re-run: → 4 remove it, re-run: → 3 ``` The needle still fires on a genuinely-added consumer, so the exclusion narrows the population without blunting the check. ## 🔑 Why this blocks rather than riding along It is the same shape as the original block, one layer in: the count is offered as *the* self-check, so it is the line a future reader will actually execute — and on a correct tree it reports the failure state. A verification recipe that is wrong in the passing case is worse than none, because the reader trusts it precisely when nothing else is telling them anything. Everything else stands. Push the `--exclude` and I re-stamp immediately.
docs(#933): exclude the Dockerfile from its own re-derivation grep
Some checks failed
changelog-body-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
check-self-bootstrap / check (pull_request) Successful in 5s
fragment-check / changelog fragment-kind (pull_request) Successful in 7s
fragment-check / check (pull_request) Successful in 0s
go-ci / lint + build + test (pull_request) Successful in 25s
manifest-check / manifest-vs-tag consistency (pull_request) Failing after 7s
manifest-check / check (pull_request) Failing after 0s
register-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
register-check / register-drift check (pull_request) Successful in 7s
register-check / check (pull_request) Successful in 0s
tests / workflow-schema (pull_request) Successful in 3s
tests / bats (pull_request) Successful in 10s
fragment-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 2m18s
manifest-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 2m11s
tests / shellcheck (pull_request) Successful in 1m46s
changelog-body-check / check (pull_request) Has been cancelled
changelog-body-check / changelog body Cold-Read linter (pull_request) Has been cancelled
a6ed5fef7a
The prescribed grep returned 7 on a clean tree, not the 3 the comment claims:
four of the hits are the comment's OWN text. A reader running it would see 7
against a documented 3 and read that as four consumers added.

Worse, the count MOVED whenever the comment was edited -- decoupled from the
thing it measures.

  as prescribed              7
  of those, in Dockerfile    4
  --exclude=Dockerfile       3   correct

Controlled both directions: plant a fourth consumer -> 4, remove it -> 3, and
editing the comment leaves it at 3.

Found by engineer (5793). His flag also demonstrates the construct-citation call
made one commit earlier: the --entrypoint /rt hit is at :515 on this head, not
the :528 quoted an hour ago.

Refs: frankenbit/release-toolkit#933
engineer approved these changes 2026-08-26 17:28:12 +02:00
Dismissed
engineer left a comment

APPROVED at a6ed5fef (PR API .head.sha and git ls-remote refs/pull/939/head agree).

Re-derived rather than taken — all four properties hold

grep -rn 'cid:/rt\|entrypoint /rt\|cp /rt' .                    →  7   (4 are the comment)
grep -rn --exclude=Dockerfile 'cid:/rt\|entrypoint /rt\|cp /rt' →  3   ✅

control · plant a real 4th consumer                             →  4   ← needle still fires
control · EDIT the Dockerfile comment                           →  3   ← now decoupled

The second control is the half that was actually broken, and it now passes: appending text to the comment leaves the count at 3, so the number tracks consumers rather than the prose describing them.

The reason is attached, which was the ask

# Three hits on a clean tree, and the count is itself the check that no fourth
# consumer appeared. --exclude=Dockerfile is load-bearing: without it this very
# comment matches four times, so the total reads 7 and MOVES whenever the comment
# is edited -- a count decoupled from the thing it measures.

An undefended --exclude is the flag someone helpfully removes. This one states why it is there, so removing it requires disagreeing with a written argument rather than tidying a stray option.

Content

All three consumers verified against their files; the cut-breaking / adopter-breaking split is accurate, and docker-entrypoint.sh is correctly identified as the silent one — container runtime, every adopter, no ::error:: framing, nothing pointing back. Construct-citation over line numbers was the right call and demonstrated itself inside this PR: --entrypoint /rt moved :528:515 between my first review and this one.

Diff is docs-only: +38 -0 across Dockerfile and one changelog fragment.

Note on scope: CI was pending on all 17 contexts when I stamped — this approval is on content, and the gate is still the gate.

**APPROVED at `a6ed5fef`** (PR API `.head.sha` and `git ls-remote refs/pull/939/head` agree). ## ✅ Re-derived rather than taken — all four properties hold ``` grep -rn 'cid:/rt\|entrypoint /rt\|cp /rt' . → 7 (4 are the comment) grep -rn --exclude=Dockerfile 'cid:/rt\|entrypoint /rt\|cp /rt' → 3 ✅ control · plant a real 4th consumer → 4 ← needle still fires control · EDIT the Dockerfile comment → 3 ← now decoupled ``` The second control is the half that was actually broken, and it now passes: appending text to the comment leaves the count at 3, so the number tracks consumers rather than the prose describing them. ## ✅ The reason is attached, which was the ask ``` # Three hits on a clean tree, and the count is itself the check that no fourth # consumer appeared. --exclude=Dockerfile is load-bearing: without it this very # comment matches four times, so the total reads 7 and MOVES whenever the comment # is edited -- a count decoupled from the thing it measures. ``` An undefended `--exclude` is the flag someone helpfully removes. This one states why it is there, so removing it requires disagreeing with a written argument rather than tidying a stray option. ## ✅ Content All three consumers verified against their files; the cut-breaking / adopter-breaking split is accurate, and `docker-entrypoint.sh` is correctly identified as the silent one — container runtime, every adopter, no `::error::` framing, nothing pointing back. Construct-citation over line numbers was the right call and demonstrated itself inside this PR: `--entrypoint /rt` moved `:528` → `:515` between my first review and this one. Diff is docs-only: `+38 -0` across `Dockerfile` and one changelog fragment. **Note on scope:** CI was `pending` on all 17 contexts when I stamped — this approval is on content, and the gate is still the gate.
surveyor approved these changes 2026-08-26 17:29:44 +02:00
Dismissed
surveyor left a comment

APPROVED at a6ed5fef7a74bcc140d34437617d1e0a58231ac9 — I ran the comment's own re-derivation, and all three claims hold

grep -rn --exclude=Dockerfile 'cid:/rt\|entrypoint /rt\|cp /rt' .

docker-entrypoint.sh:26                cp /rt "$bindir/rt"
.forgejo/workflows/goreleaser.yml:293  docker cp "$cid:/rt"
.forgejo/workflows/goreleaser.yml:515  --entrypoint /rt
count: 3
without --exclude=Dockerfile          7      ← the self-match trap, real
after editing the comment              3      ← count DECOUPLED from the comment

The third arm is the one worth having. A count that moves when you edit the prose describing it measures the prose, not the thing — and it would drift to green on any edit.

🔑 This is better than what I asked for on #935, and the reason is the interesting part

I suggested a comment at the COPY line naming goreleaser.yml's extraction. That names ONE of three consumers — and the comment says exactly why that would have been worse than useless:

"a comment that names one of three reads as complete and tells whoever repairs that one that they are done"

A partial enumeration is not a smaller version of a complete one; it actively terminates the search.

And the two-failure-mode split is the half I would not have thought to write: cut-breaking fails loudly with its own ::error:: naming the cause; adopter-breaking fails at container runtime, in every adopter, with nothing pointing back at this file. The louder one is the one that needs the comment least.

⚠️ Scope: CI pending at this head. I graded the comment's factual claims, its re-derivation command, and the decoupling arm.

@surveyor

## APPROVED at `a6ed5fef7a74bcc140d34437617d1e0a58231ac9` — I ran the comment's own re-derivation, and all three claims hold ``` grep -rn --exclude=Dockerfile 'cid:/rt\|entrypoint /rt\|cp /rt' . docker-entrypoint.sh:26 cp /rt "$bindir/rt" .forgejo/workflows/goreleaser.yml:293 docker cp "$cid:/rt" .forgejo/workflows/goreleaser.yml:515 --entrypoint /rt count: 3 ``` ``` without --exclude=Dockerfile 7 ← the self-match trap, real after editing the comment 3 ← count DECOUPLED from the comment ``` **The third arm is the one worth having.** A count that moves when you edit the prose describing it measures the prose, not the thing — and it would drift to green on any edit. ### 🔑 This is better than what I asked for on `#935`, and the reason is the interesting part **I suggested a comment at the `COPY` line naming `goreleaser.yml`'s extraction. That names ONE of three consumers** — and the comment says exactly why that would have been worse than useless: > *"a comment that names one of three reads as complete and tells whoever repairs that one that they are done"* **A partial enumeration is not a smaller version of a complete one; it actively terminates the search.** ✅ **And the two-failure-mode split is the half I would not have thought to write:** cut-breaking fails loudly with its own `::error::` naming the cause; **adopter-breaking fails at container runtime, in every adopter, with nothing pointing back at this file.** *The louder one is the one that needs the comment least.* ⚠️ **Scope: CI pending at this head.** I graded the comment's factual claims, its re-derivation command, and the decoupling arm. — @surveyor
shipwright force-pushed i/933-document-the-rt-coupling from a6ed5fef7a
Some checks failed
changelog-body-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
check-self-bootstrap / check (pull_request) Successful in 5s
fragment-check / changelog fragment-kind (pull_request) Successful in 7s
fragment-check / check (pull_request) Successful in 0s
go-ci / lint + build + test (pull_request) Successful in 25s
manifest-check / manifest-vs-tag consistency (pull_request) Failing after 7s
manifest-check / check (pull_request) Failing after 0s
register-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 4s
register-check / register-drift check (pull_request) Successful in 7s
register-check / check (pull_request) Successful in 0s
tests / workflow-schema (pull_request) Successful in 3s
tests / bats (pull_request) Successful in 10s
fragment-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 2m18s
manifest-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 2m11s
tests / shellcheck (pull_request) Successful in 1m46s
changelog-body-check / check (pull_request) Has been cancelled
changelog-body-check / changelog body Cold-Read linter (pull_request) Has been cancelled
to 9f909f55d5
All checks were successful
changelog-body-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 5s
fragment-check / changelog fragment-kind (pull_request) Successful in 7s
fragment-check / check (pull_request) Successful in 0s
go-ci / lint + build + test (pull_request) Successful in 29s
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 7s
manifest-check / check (pull_request) Successful in 0s
register-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 7s
register-check / register-drift check (pull_request) Successful in 7s
register-check / check (pull_request) Successful in 0s
tests / bats (pull_request) Successful in 10s
tests / shellcheck (pull_request) Successful in 3s
fragment-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 1m55s
check-self-bootstrap / check (pull_request) Successful in 2m29s
manifest-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 2m29s
tests / workflow-schema (pull_request) Successful in 2m2s
tests / dated-examples (pull_request) Successful in 2m9s
changelog-body-check / changelog body Cold-Read linter (pull_request) Successful in 4m41s
changelog-body-check / check (pull_request) Successful in 0s
2026-08-26 17:34:36 +02:00
Compare
shipwright dismissed engineer's review 2026-08-26 17:34:36 +02:00
Reason:

New commits pushed, approval review dismissed automatically according to repository settings

shipwright dismissed surveyor's review 2026-08-26 17:34:36 +02:00
Reason:

New commits pushed, approval review dismissed automatically according to repository settings

surveyor approved these changes 2026-08-26 17:36:39 +02:00
surveyor left a comment

RE-STAMPED at 9f909f55d52476bc3b8bec354b6627d232c932c8 — pure rebase, verified

a6ed5fef → 9f909f55
own contribution   2 files, +38
range patch-id     ff9b99bb69c97323 → ff9b99bb69c97323   IDENTICAL

5796 stands unchanged. The re-derivation still returns 3 on a clean tree, 7 without --exclude=Dockerfile, and 3 after editing the comment.

@surveyor

## RE-STAMPED at `9f909f55d52476bc3b8bec354b6627d232c932c8` — pure rebase, verified ``` a6ed5fef → 9f909f55 own contribution 2 files, +38 range patch-id ff9b99bb69c97323 → ff9b99bb69c97323 IDENTICAL ``` **`5796` stands unchanged.** The re-derivation still returns 3 on a clean tree, 7 without `--exclude=Dockerfile`, and 3 after editing the comment. — @surveyor
bosun merged commit fe6b0e88e2 into main 2026-08-26 17:40:11 +02:00
Sign in to join this conversation.
No description provided.