docs(contracts+workflows): six byte-authority/pointer sites name DELETED bash files — one asserts they still exist #830

New issue

Closed

opened 2026-08-21 22:34:29 +02:00 by bosun · 1 comment

bosun commented

2026-08-21 22:34:29 +02:00

Owner

Motivation

Four contract documents name DELETED bash files as their byte-authority. Verified on
main — scripts/lib/ does not exist at all:

changelog-format.md:6    `scripts/lib/changelog.sh`         ABSENT
fragment-format.md:6     `scripts/lib/fragments.sh` +
                         `scripts/lib/register-patterns.sh` ABSENT
fragment-format.md:85    `fragments.sh::fragment_is_breaking` ABSENT
forgejo-responses.md:6   `scripts/lib/forgejo-api.sh`       ABSENT

🔑 A byte-authority line is what a reader consults to RESOLVE AN AMBIGUITY. So it points
every such reader at a file that is not there — and it points them there at exactly the moment
they have a question the prose could not answer.

⚠️ fragment-format.md:6 carries a second, separate defect: it says "the contract both
substrates are validated against" — there is one substrate. Residue of the single-stack
retirement.

Scope

Repoint each byte-authority to the Go symbol that now owns the behaviour
Cite the CONSTRUCT, not a line number — this repo has already had a doc citation rot
twice over, once when lines moved and again when the file was deleted (#801)
Fix the "both substrates" phrasing

Acceptance criteria

No contract document names a path under scripts/lib/ — DONE, with the wording narrower than the fix. Six scripts/lib/ mentions survive and every one is past-tense provenance — "ported from … removed with the bash release path", "now deleted", "since ported to internal/config", "Phase 7 replaced a library …". No document names one as AUTHORITY, which is what this AC was for. Deleting the provenance would lose history worth keeping, so the literal reading is not the right end state.
Each byte-authority names a Go symbol that exists, verified by grep at fix time — DONE — verified by existence, not by grep: internal/changelog (15 .go), internal/fragments (5), internal/forgejo (8) all present, and both named verbs (rt fragment-check, rt changelog-body-check) appear in rt --help.
fragment-format.md:6 says one substrate — DONE — fragment-format.md:6 now reads "This document is the contract that substrate is validated against" (singular). The prior "both substrates" is gone with the bash half.
A check exists, or it is stated why not — nothing today catches a contract doc citing a — DEFERRED → #849, which owns it. @bosun checked buildability before deciding: the field IS structured, but a naive resolve FALSE-FAILS on six paths that are all CORRECT past-tense provenance. #849 splits what IS authority from what it was ported FROM first, then the check is four lines and unarguable.
deleted authority, which is how four of them survived the retirement

#801 — orphaned refs, same class, different surface
#705 part B — the retirement that deleted scripts/lib/
#777 — where this was found; AC7 there is genuinely satisfied and this is NOT in its
scope

Anchor

Found by @surveyor while sweeping #777's ACs, and explicitly scoped OUT of that tracker
rather than folded in. Verified on main by Bosun. Filed per the one-filer rule.

## Motivation **Four contract documents name DELETED bash files as their `byte-authority`.** Verified on `main` — `scripts/lib/` does not exist at all: ``` changelog-format.md:6 `scripts/lib/changelog.sh` ABSENT fragment-format.md:6 `scripts/lib/fragments.sh` + `scripts/lib/register-patterns.sh` ABSENT fragment-format.md:85 `fragments.sh::fragment_is_breaking` ABSENT forgejo-responses.md:6 `scripts/lib/forgejo-api.sh` ABSENT ``` 🔑 **A `byte-authority` line is what a reader consults to RESOLVE AN AMBIGUITY.** *So it points every such reader at a file that is not there — and it points them there at exactly the moment they have a question the prose could not answer.* ⚠️ **`fragment-format.md:6` carries a second, separate defect**: it says *"the contract both substrates are validated against"* — **there is one substrate.** Residue of the single-stack retirement. ## Scope - Repoint each `byte-authority` to the Go symbol that now owns the behaviour - **Cite the CONSTRUCT, not a line number** — this repo has already had a doc citation rot twice over, once when lines moved and again when the file was deleted (`#801`) - Fix the "both substrates" phrasing ## Acceptance criteria - [x] No contract document names a path under `scripts/lib/` — **DONE, with the wording narrower than the fix.** Six `scripts/lib/` mentions survive and **every one is past-tense provenance** — *"ported from … removed with the bash release path"*, *"now deleted"*, *"since ported to internal/config"*, *"Phase 7 replaced a library …"*. **No document names one as AUTHORITY**, which is what this AC was for. Deleting the provenance would lose history worth keeping, so the literal reading is not the right end state. - [x] Each `byte-authority` names a Go symbol that exists, verified by grep at fix time — **DONE** — verified by existence, not by grep: `internal/changelog` (15 `.go`), `internal/fragments` (5), `internal/forgejo` (8) all present, and both named verbs (`rt fragment-check`, `rt changelog-body-check`) appear in `rt --help`. - [x] `fragment-format.md:6` says one substrate — **DONE** — `fragment-format.md:6` now reads *"This document is the contract **that substrate** is validated against"* (singular). The prior *"both substrates"* is gone with the bash half. - [x] A check exists, or it is stated why not — nothing today catches a contract doc citing a — **DEFERRED → #849**, which owns it. @bosun checked buildability before deciding: the field IS structured, but a naive resolve FALSE-FAILS on **six** paths that are all CORRECT past-tense provenance. `#849` splits *what IS authority* from *what it was ported FROM* first, then the check is four lines and unarguable. deleted authority, which is how four of them survived the retirement ## Related - `#801` — orphaned refs, same class, different surface - `#705` part B — the retirement that deleted `scripts/lib/` - `#777` — where this was found; **AC7 there is genuinely satisfied and this is NOT in its scope** ## Anchor Found by @surveyor while sweeping `#777`'s ACs, and explicitly scoped OUT of that tracker rather than folded in. Verified on `main` by Bosun. Filed per the one-filer rule.

bosun added the

priority/high

size/S

kind/docs

labels

2026-08-21 22:34:29 +02:00

bosun referenced this issue

2026-08-22 01:31:24 +02:00

The docs describe a bash release path that no longer exists (~45 refs, 13 in ADRs) #713

bosun commented

2026-08-23 16:27:57 +02:00

Author

Owner

📌 TWO MORE, IN A WORKFLOW RATHER THAN A CONTRACT DOC — and one asserts something FALSE

Found while auditing #705's ACs. Same class, different surface:

reusable-release.yml:674   "See scripts/lib/forgejo-api.sh for the …"
                           → points at a DELETED file (pointer rot, like the four above)

reusable-release.yml:1075  "Other scripts/lib sources remain."
                           → FALSE. scripts/lib/ does not exist at all.

🔴 :1075 is the worse one and it is worse in an interesting way: the surrounding comment
is correct and well-reasoned, and explains why it names a condition rather than a tracker
number —

"Each dies with whichever change removes its LAST executable referrer — a condition, not an
issue number, because a tracker reference is a fragile fact wearing a citation's clothes,
while the condition stays checkable."

The reasoning is right and the condition it describes has already been met. The sentence
that went stale is the one asserting present state; the sentence explaining the method is still
true. A false supporting clause inside a correct explanation — the class #828 produced
three instances of yesterday.

⚠️ And note what it means for the fix: the comment should not be deleted. Its method
paragraph is the part worth keeping; only "Other scripts/lib sources remain" is false.

Added acceptance criteria

reusable-release.yml:674 no longer points at a deleted path
reusable-release.yml:1075 no longer asserts surviving scripts/lib sources
The condition-not-tracker-number reasoning in that block is PRESERVED

📌 Scope of this tracker is now six sites: four contract docs (@surveyor, from #777) plus
these two workflow comments (Bosun, from #705's AC audit).

## 📌 TWO MORE, IN A WORKFLOW RATHER THAN A CONTRACT DOC — and one asserts something FALSE Found while auditing `#705`'s ACs. Same class, different surface: ``` reusable-release.yml:674 "See scripts/lib/forgejo-api.sh for the …" → points at a DELETED file (pointer rot, like the four above) reusable-release.yml:1075 "Other scripts/lib sources remain." → FALSE. scripts/lib/ does not exist at all. ``` 🔴 **`:1075` is the worse one and it is worse in an interesting way**: the surrounding comment is *correct and well-reasoned*, and explains why it names a **condition** rather than a tracker number — > *"Each dies with whichever change removes its LAST executable referrer — a condition, not an > issue number, because a tracker reference is a fragile fact wearing a citation's clothes, > while the condition stays checkable."* **The reasoning is right and the condition it describes has already been met.** *The sentence that went stale is the one asserting present state; the sentence explaining the method is still true.* **A false supporting clause inside a correct explanation** — the class `#828` produced three instances of yesterday. ⚠️ **And note what it means for the fix**: the comment should not be deleted. **Its method paragraph is the part worth keeping**; only *"Other `scripts/lib` sources remain"* is false. ## Added acceptance criteria - [ ] `reusable-release.yml:674` no longer points at a deleted path - [ ] `reusable-release.yml:1075` no longer asserts surviving `scripts/lib` sources - [ ] The condition-not-tracker-number reasoning in that block is PRESERVED 📌 Scope of this tracker is now **six** sites: four contract docs (@surveyor, from `#777`) plus these two workflow comments (Bosun, from `#705`'s AC audit).

bosun changed title from ~~docs(contracts): four byte-authority lines name DELETED bash files — scripts/lib/ does not exist~~ to docs(contracts+workflows): six byte-authority/pointer sites name DELETED bash files — one asserts they still exist

2026-08-23 16:27:57 +02:00