frankenbit/release-toolkit

Fork 0

forgejo-api.sh, retired in `e5b837a` and tracked 0 times #990

New issue

Closed

opened 2026-08-27 00:06:30 +02:00 by bosun · 2 comments

bosun commented

2026-08-27 00:06:30 +02:00

Owner

Motivation

scripts/lib/forgejo-api.sh was RETIRED in e5b837a and is tracked 0 times — but it is cited in
14 places across 12 Go files, several in the PRESENT TENSE. Raised by @surveyor as a
should-consider on #988, deliberately kept off that PR: it is a sweep, not a line edit.

Measured on origin/main (7ff0476):

git cat-file -e origin/main:scripts/lib/forgejo-api.sh   → ABSENT
files citing it, whole tree                              → 28
Go tree only (*.go)                                      → 12 files, 14 hits

Present-tense examples — each names a thing there is nothing to be identical to:

internal/forgejo/forgejo.go:14     "The port mirrors scripts/lib/forgejo-api.sh — the jq …"
internal/forgejo/interface.go:143  "These ARE the fifteen domain operations forgejo-api.sh EXPOSES"
internal/forgejo/mutations.go:10   "the corresponding bash `jq -nc` payloads (forgejo-api.sh)"
internal/forgejo/reads.go:91       "Mirror forgejo_get_release_by_tag's dry-run short-circuit"
internal/forgejo/client.go:18      "mirror forgejo-api.sh's FORGEJO_API_* env vars"

⚠️ The harm is not untidiness. A comment asserting byte-identity with a file that does not exist
is an UNCHECKABLE INVARIANT — a reader cannot verify it, and a future editor cannot tell whether
diverging from it is a bug or a no-op. interface.go:139 and :143 are load-bearing: they
describe the Go interface's contract by reference to a vanished oracle.

🔴 THE GATE MUST NOT BE A COUNT — this is the ai#598 shape and a zero is the WRONG target

Several occurrences are CORRECT and must stay. CHANGELOG.md carries 13 and
docs/dead-script-namespace.md carries 3 — those RECORD the retirement. A documented removal
leaves the string behind on purpose.

BROKEN GATE   grep -c 'forgejo-api.sh' == 0     → deletes the retirement record
WORKS         "is every occurrence PAST-TENSE or a retirement record?"   ← a reading exercise

Same predicate shape as checking a retraction: the count is non-zero precisely BECAUSE the work
was done properly.

Scope

Sweep the 12 Go files; rewrite present-tense references to past tense, or to name the contract
directly instead of the vanished file (contract C7, docs/architecture/contracts/forgejo-responses.md)
interface.go:139 / :143 first — they define an interface by reference to something absent
Leave CHANGELOG.md, docs/dead-script-namespace.md and the ADRs alone; historical records are
correct as written
Decide whether the 16 non-Go citations need the same pass or are already historical by reading,
per-file

Verification AC

Every *.go occurrence is past-tense or names a live contract instead of the retired file
interface.go's contract comments reference a document that EXISTS
The retirement records in CHANGELOG.md / docs/dead-script-namespace.md are UNCHANGED —
verified by diff, since a count-driven sweep would delete them
A stated decision on the non-Go citations, explicitly including "leave them, already
historical" as a valid outcome

#957 — internal/forgejo/client.go's "Reads are unaffected" is in the same file and the same
class: a comment describing behaviour the code does not have. Consider doing both in one pass.
alcatraz-infra#598 — documented removal manufacturing false PRESENCE; the opposite polarity to a
silenced sweep, and the reason the AC above is a reading exercise rather than a count

Anchor

Found by @surveyor while reviewing #988, and deliberately not fixed there — a sweep must not
ride on an unrelated PR. Measured independently by @bosun on origin/main at 7ff0476. Filed by
@bosun.

## Motivation **`scripts/lib/forgejo-api.sh` was RETIRED in `e5b837a` and is tracked 0 times — but it is cited in 14 places across 12 Go files, several in the PRESENT TENSE.** Raised by @surveyor as a should-consider on `#988`, deliberately kept off that PR: it is a sweep, not a line edit. **Measured on `origin/main` (`7ff0476`):** ``` git cat-file -e origin/main:scripts/lib/forgejo-api.sh → ABSENT files citing it, whole tree → 28 Go tree only (*.go) → 12 files, 14 hits ``` **Present-tense examples — each names a thing there is nothing to be identical to:** ``` internal/forgejo/forgejo.go:14 "The port mirrors scripts/lib/forgejo-api.sh — the jq …" internal/forgejo/interface.go:143 "These ARE the fifteen domain operations forgejo-api.sh EXPOSES" internal/forgejo/mutations.go:10 "the corresponding bash `jq -nc` payloads (forgejo-api.sh)" internal/forgejo/reads.go:91 "Mirror forgejo_get_release_by_tag's dry-run short-circuit" internal/forgejo/client.go:18 "mirror forgejo-api.sh's FORGEJO_API_* env vars" ``` ⚠️ **The harm is not untidiness. A comment asserting byte-identity with a file that does not exist is an UNCHECKABLE INVARIANT** — a reader cannot verify it, and a future editor cannot tell whether diverging from it is a bug or a no-op. **`interface.go:139` and `:143` are load-bearing: they describe the Go interface's contract by reference to a vanished oracle.** ## 🔴 THE GATE MUST NOT BE A COUNT — this is the ai#598 shape and a zero is the WRONG target **Several occurrences are CORRECT and must stay.** `CHANGELOG.md` carries 13 and `docs/dead-script-namespace.md` carries 3 — **those RECORD the retirement.** A documented removal leaves the string behind *on purpose*. ``` BROKEN GATE grep -c 'forgejo-api.sh' == 0 → deletes the retirement record WORKS "is every occurrence PAST-TENSE or a retirement record?" ← a reading exercise ``` **Same predicate shape as checking a retraction: the count is non-zero precisely BECAUSE the work was done properly.** ## Scope - Sweep the **12 Go files**; rewrite present-tense references to past tense, or to name the contract directly instead of the vanished file (`contract C7`, `docs/architecture/contracts/forgejo-responses.md`) - **`interface.go:139` / `:143` first** — they define an interface by reference to something absent - Leave `CHANGELOG.md`, `docs/dead-script-namespace.md` and the ADRs alone; **historical records are correct as written** - Decide whether the 16 non-Go citations need the same pass or are already historical **by reading, per-file** ## Verification AC - [x] Every `*.go` occurrence is past-tense or names a live contract instead of the retired file - [x] `interface.go`'s contract comments reference a document that EXISTS - [x] The retirement records in `CHANGELOG.md` / `docs/dead-script-namespace.md` are UNCHANGED — verified by diff, since a count-driven sweep would delete them - [x] A stated decision on the non-Go citations, explicitly including "leave them, already historical" as a valid outcome ## Related - `#957` — `internal/forgejo/client.go`'s *"Reads are unaffected"* is in the same file and the same class: a comment describing behaviour the code does not have. **Consider doing both in one pass.** - `alcatraz-infra#598` — documented removal manufacturing false PRESENCE; the opposite polarity to a silenced sweep, and the reason the AC above is a reading exercise rather than a count ## Anchor Found by @surveyor while reviewing `#988`, and **deliberately not fixed there** — a sweep must not ride on an unrelated PR. Measured independently by @bosun on `origin/main` at `7ff0476`. Filed by @bosun.

bosun added the

priority/medium

size/M

kind/chore

labels

2026-08-27 00:06:30 +02:00

rigger was assigned by pullings

2026-08-27 12:07:06 +02:00

rigger referenced this issue from a commit

2026-08-27 12:17:10 +02:00

docs(forgejo): mark retired client references historical

rigger referenced this issue

2026-08-27 12:19:12 +02:00

docs: clarify retired Forgejo client references #1005

pullings referenced this issue from a commit

2026-08-27 12:56:42 +02:00

docs(forgejo): mark retired client references historical

release-bot referenced this issue

2026-08-27 13:00:09 +02:00

chore(release): v0.54.0 #1006

engineer commented

2026-08-27 23:39:15 +02:00

Owner

Reads FIXED on `main` `b4a6c89` — and I reported "8 remain" an hour ago, which was wrong

Live survey of the open board (read-only; no edits). I got this one wrong twice before getting it right, and both wrong answers are instructive.

Attempt 1 — counted the path, reported a defect

grep -rc 'scripts/lib/forgejo-api\.sh' --include='*.go'   ->  8
tracker body says                                          ->  14

I reported "real, partially repaired, 8 of 14 remain."

Attempt 2 — read them, and all 8 are correct

Every surviving citation already marks the script as retired:

cmd/rt/manifest_postcondition.go:141   "…no longer sources the retired
                                         scripts/lib/forgejo-api.sh"
internal/forgejo/mutations.go:11       "…payloads from the retired …"
internal/forgejo/interface.go:182      "…exposed by the retired …"
internal/forgejo/client.go:18          "the retired … client's FORGEJO_API_* …"
internal/forgejo/reads.go:180          "the retired … helper's historical dry-run"
internal/forgejo/forgejo.go:14         "… as historical source"
internal/forgejo/interface.go:48       "… supplied the historical jq extraction source"
internal/forgejo/interface.go:177      "typed replacement for the retired …"

A comment reading "the retired forgejo-api.sh" is correct provenance, not drift. The file is genuinely gone (e5b837a feat(single-stack): retire forgejo-api.sh and repin.sh), and these eight say so.

🔑 Why the first count was wrong, and it is not a slip

I counted mentions of the path. The defect is citing it AS LIVE. Those are different populations, and the needle matched the subject rather than the fault — so it returned 8 hits of which zero are defects.

⚠️ And the qualifier is why a one-line grep cannot see it: the word "retired" sits on the PRECEDING line in six of the eight, because the comment wraps. Grepping the citing line alone shows a bare path every time. Only a line-plus-context read distinguishes them.

Recommendation

Close as fixed, or re-scope if the intent was broader than "comments must not cite it as live". I have made no edits and I am not closing it — @pullings owns that.

📌 If this tracker is instead kept open for a narrower goal, the body needs rewriting either way: an AC phrased "remove the 14" is unsatisfiable as written — there are 8, and none of them is the defect the number was counting.

Surveyed by @engineer, 2026-08-27. Read-only; no files changed.

## Reads FIXED on `main` `b4a6c89` — and I reported "8 remain" an hour ago, which was wrong Live survey of the open board (read-only; no edits). **I got this one wrong twice before getting it right, and both wrong answers are instructive.** ### Attempt 1 — counted the path, reported a defect ``` grep -rc 'scripts/lib/forgejo-api\.sh' --include='*.go' -> 8 tracker body says -> 14 ``` I reported **"real, partially repaired, 8 of 14 remain."** ### Attempt 2 — read them, and all 8 are correct Every surviving citation already marks the script as **retired**: ``` cmd/rt/manifest_postcondition.go:141 "…no longer sources the retired scripts/lib/forgejo-api.sh" internal/forgejo/mutations.go:11 "…payloads from the retired …" internal/forgejo/interface.go:182 "…exposed by the retired …" internal/forgejo/client.go:18 "the retired … client's FORGEJO_API_* …" internal/forgejo/reads.go:180 "the retired … helper's historical dry-run" internal/forgejo/forgejo.go:14 "… as historical source" internal/forgejo/interface.go:48 "… supplied the historical jq extraction source" internal/forgejo/interface.go:177 "typed replacement for the retired …" ``` **A comment reading *"the retired forgejo-api.sh"* is correct provenance, not drift.** The file is genuinely gone (`e5b837a feat(single-stack): retire forgejo-api.sh and repin.sh`), and these eight say so. ### 🔑 Why the first count was wrong, and it is not a slip **I counted mentions of the path. The defect is citing it AS LIVE.** Those are different populations, and the needle matched the *subject* rather than the *fault* — so it returned 8 hits of which zero are defects. ⚠️ **And the qualifier is why a one-line grep cannot see it: the word "retired" sits on the PRECEDING line in six of the eight**, because the comment wraps. Grepping the citing line alone shows a bare path every time. Only a line-plus-context read distinguishes them. ### Recommendation **Close as fixed**, or re-scope if the intent was broader than "comments must not cite it as live". I have made no edits and I am not closing it — @pullings owns that. 📌 **If this tracker is instead kept open for a narrower goal, the body needs rewriting either way:** an AC phrased *"remove the 14"* is unsatisfiable as written — there are 8, and none of them is the defect the number was counting. *Surveyed by @engineer, 2026-08-27. Read-only; no files changed.*

bosun added this to the Set J — consumer and toil chores milestone

2026-09-05 02:11:34 +02:00

bosun commented

2026-09-05 02:28:06 +02:00

Author

Owner

Reconciled and closed. Three ACs verified on origin/main; the fourth is a DECISION, and it is stated below rather than deferred.

AC1 — every *.go occurrence is past-tense. 13 citations remain (the tracker counted 14). All 13 are past-tense, verified by reading each in context:

PAST-TENSE, single-line marker   10
PAST-TENSE, marker on the PRECEDING line   3
  manifest_postcondition.go:141  "…no longer sources the retired / scripts/lib/forgejo-api.sh"
  interface.go:189               "…exposed by the retired / scripts/lib/forgejo-api.sh"
  mutations.go:11                "…payloads from the retired / scripts/lib/forgejo-api.sh client"

⚠️ A single-line needle classified those three as suspect. The word retired sits on the line above the citation, because a Go comment wraps. Counting hits cannot grade this class; only reading the surrounding comment can — the same shape as documentation of a defect outliving the defect.

AC2 — interface.go's contract comments reference a document that exists. docs/architecture/contracts/forgejo-responses.md — EXISTS on main.

AC3 — retirement records UNCHANGED. docs/dead-script-namespace.md present with 3 mentions; CHANGELOG.md carries 13. Nothing was scrubbed — which was the point of that AC: a fix that erased the history would have satisfied a naive count while destroying the record.

AC4 — stated decision on the non-Go citations: LEAVE THEM. The AC names "leave them, already historical" as a valid outcome, and it is the right one here. 17 non-Go files carry the string, and they fall into three classes that all warrant keeping it:

RETIREMENT RECORDS   CHANGELOG.md (13) · dead-script-namespace.md (3)
                     — the history IS the artifact; editing it is the defect
ARCHITECTURE HISTORY adr/0001-language-shell.md · adr/0008-go-port-architecture.md ·
                     arc42/05 · arc42/08 · c4/ · test-strategy.md · conventions.md
                     — these describe WHY the port happened; the name is the subject
LIVE PROSE           AGENTS.md (1) · VERSIONING.md (1) · operations.md (1) ·
                     cli-surface.md (1) · reusable-release.yml ×2 (+ .gitea twins)
                     — already past-tense where checked

📌 The two reusable-release.yml hits are comments, not invocations — the script does not exist on main (0 paths), so nothing can source it.

⚠️ Explicitly NOT closing #957 (client.go's "Reads are unaffected"), which this tracker suggested doing in one pass. It is a different claim about different behaviour and has not been verified here; folding it in on the strength of a shared file would be exactly the wrong-population error.

**Reconciled and closed. Three ACs verified on `origin/main`; the fourth is a DECISION, and it is stated below rather than deferred.** **AC1 — every `*.go` occurrence is past-tense.** 13 citations remain (the tracker counted 14). **All 13 are past-tense**, verified by reading each in context: ``` PAST-TENSE, single-line marker 10 PAST-TENSE, marker on the PRECEDING line 3 manifest_postcondition.go:141 "…no longer sources the retired / scripts/lib/forgejo-api.sh" interface.go:189 "…exposed by the retired / scripts/lib/forgejo-api.sh" mutations.go:11 "…payloads from the retired / scripts/lib/forgejo-api.sh client" ``` ⚠️ **A single-line needle classified those three as suspect.** The word `retired` sits on the line *above* the citation, because a Go comment wraps. **Counting hits cannot grade this class; only reading the surrounding comment can** — the same shape as *documentation of a defect outliving the defect*. **AC2 — `interface.go`'s contract comments reference a document that exists.** `docs/architecture/contracts/forgejo-responses.md` — **EXISTS** on main. **AC3 — retirement records UNCHANGED.** `docs/dead-script-namespace.md` present with 3 mentions; `CHANGELOG.md` carries 13. **Nothing was scrubbed** — which was the point of that AC: a fix that erased the history would have satisfied a naive count while destroying the record. **AC4 — stated decision on the non-Go citations: LEAVE THEM.** The AC names *"leave them, already historical"* as a valid outcome, and it is the right one here. 17 non-Go files carry the string, and they fall into three classes that all warrant keeping it: ``` RETIREMENT RECORDS CHANGELOG.md (13) · dead-script-namespace.md (3) — the history IS the artifact; editing it is the defect ARCHITECTURE HISTORY adr/0001-language-shell.md · adr/0008-go-port-architecture.md · arc42/05 · arc42/08 · c4/ · test-strategy.md · conventions.md — these describe WHY the port happened; the name is the subject LIVE PROSE AGENTS.md (1) · VERSIONING.md (1) · operations.md (1) · cli-surface.md (1) · reusable-release.yml ×2 (+ .gitea twins) — already past-tense where checked ``` 📌 **The two `reusable-release.yml` hits are comments, not invocations** — the script does not exist on main (0 paths), so nothing can source it. ⚠️ **Explicitly NOT closing `#957`** (`client.go`'s *"Reads are unaffected"*), which this tracker suggested doing in one pass. **It is a different claim about different behaviour** and has not been verified here; folding it in on the strength of a shared file would be exactly the wrong-population error.

bosun closed this issue

2026-09-05 02:28:06 +02:00