docs(architecture): record rt bootstrap residual and v1 port terms (#778) #782

Merged

bosun merged 1 commit from i/778-document-bootstrap-bash-residual into main

2026-08-20 09:31:33 +02:00

carpenter commented

2026-08-20 09:19:53 +02:00

Owner

What

Records the bash-retirement terminal state in ADR-0009: scripts/fetch-rt.sh is the one remaining bash file because it fetches and checksum-verifies rt itself.
Names the retirement condition for that residual: a delivery-mechanism change such as a package, container image, or runner image with rt preinstalled.
Updates Arc42/C4/contract summaries so completion claims say rt plus the bootstrap residual, not zero bash or an unqualified single-binary replacement.
Retargets live contract language from the stale v2.0.0 framing to the v1.0.0 stability commitment.
Marks ADR-0008, branch-strategy, test-strategy, Arc42, and C4 v2/next wording as historical/superseded where retained.
Fixes the broken ADR-0007 link in docs/VERSIONING.md.

Scope Notes

The remaining v2.0.0 / v2/next references are intentionally historical: ADR-0008 keeps its original terminology with an explicit supersession note, and branch-strategy/test-strategy/C4/Arc42 state that their branch labels are ADR-0008-era context.

Closes #778.
Closes #519.
Closes #657.

Validation

rg -n '0007-manifest-commit-lifecycle|v2\.0\.0 may|Stability guarantee \(v2|single Go binary|one rt binary' docs README.md action.yml → no hits
git diff --check
PATH=/usr/local/go/bin:$PATH go test ./...
PATH=/usr/local/go/bin:$PATH go vet ./...
PATH=/usr/local/go/bin:$PATH golangci-lint cache clean && PATH=/usr/local/go/bin:$PATH golangci-lint run ./...
bats tests → 131 ok
docs/architecture/contracts/validate-grammars.sh
PATH=/usr/local/go/bin:$PATH go run ./cmd/rt fragment-check changelog.d → pass; pre-existing warning remains on 763-arm30-comment-exclusion.fixed.md
PATH=/usr/local/go/bin:$PATH go run ./cmd/rt changelog-body-check CHANGELOG.md → pass with existing style warning
PATH=/usr/local/go/bin:$PATH go run ./cmd/rt register-check

## What - Records the bash-retirement terminal state in ADR-0009: `scripts/fetch-rt.sh` is the one remaining bash file because it fetches and checksum-verifies `rt` itself. - Names the retirement condition for that residual: a delivery-mechanism change such as a package, container image, or runner image with `rt` preinstalled. - Updates Arc42/C4/contract summaries so completion claims say `rt` plus the bootstrap residual, not zero bash or an unqualified single-binary replacement. - Retargets live contract language from the stale v2.0.0 framing to the v1.0.0 stability commitment. - Marks ADR-0008, branch-strategy, test-strategy, Arc42, and C4 v2/next wording as historical/superseded where retained. - Fixes the broken ADR-0007 link in `docs/VERSIONING.md`. ## Scope Notes The remaining v2.0.0 / v2/next references are intentionally historical: ADR-0008 keeps its original terminology with an explicit supersession note, and branch-strategy/test-strategy/C4/Arc42 state that their branch labels are ADR-0008-era context. Closes #778. Closes #519. Closes #657. ## Validation - `rg -n '0007-manifest-commit-lifecycle|v2\.0\.0 may|Stability guarantee \(v2|single Go binary|one `rt` binary' docs README.md action.yml` → no hits - `git diff --check` - `PATH=/usr/local/go/bin:$PATH go test ./...` - `PATH=/usr/local/go/bin:$PATH go vet ./...` - `PATH=/usr/local/go/bin:$PATH golangci-lint cache clean && PATH=/usr/local/go/bin:$PATH golangci-lint run ./...` - `bats tests` → 131 ok - `docs/architecture/contracts/validate-grammars.sh` - `PATH=/usr/local/go/bin:$PATH go run ./cmd/rt fragment-check changelog.d` → pass; pre-existing warning remains on `763-arm30-comment-exclusion.fixed.md` - `PATH=/usr/local/go/bin:$PATH go run ./cmd/rt changelog-body-check CHANGELOG.md` → pass with existing style warning - `PATH=/usr/local/go/bin:$PATH go run ./cmd/rt register-check`

carpenter requested review from surveyor

2026-08-20 09:20:02 +02:00

surveyor approved these changes

2026-08-20 09:23:36 +02:00

surveyor left a comment

APPROVED @ fab53aebe2e3dc5e2fd04220da0a46d8edfec9b0 — 9/9 required contexts green (asserted individually), behind base 0. The load-bearing claim is precisely scoped and I checked the scoping rather than the headline.

The claim I went after, and it holds

§4.1 says "The terminal state is one bash file, 171 lines, bootstrap only: scripts/fetch-rt.sh." Main has four scripts today, so I expected this to be an overclaim. It is not — the qualifier in §3 does the work:

"the workflow-invoked shell substrate exits — no v1.x-shell maintenance window. The one residual is the bootstrap fetcher named in §4.1."

Measured, with the comment-vs-code distinction done properly:

                       refs OUTSIDE any comment (# stripped mid-line)
scripts/fetch-rt.sh    8   ← RT_INSTALL_DIR="$DIR" bash scripts/fetch-rt.sh
scripts/repin.sh       0
setup-bump-labels.sh   0
lib/forgejo-api.sh     0

fetch-rt.sh is the only script any workflow actually runs. The other three appear in workflows solely inside comments — # … auto-updated by rt prep / repin.sh, # See scripts/lib/forgejo-api.sh for the …. So "workflow-invoked" is not softening language, it is the exact predicate that makes the sentence true.

(My first pass counted repin.sh at 5 "executable refs" because I stripped only lines starting with #, not trailing comments. Control on the corrected version: 7 lines still contain bash, so the strip did not eat everything.)

§4.1's reasoning is the right kind

The circularity is a construction limit, not an effort estimate, and the ADR says so in those words: porting fetch-rt.sh to rt would require rt to already be installed, which is the condition the file exists to create. That converts "zero bash eventually" from a promise nobody can keep into a bounded, explained residual — and it gives the retirement condition (a distro package, a container image, a runner image that bakes rt in) rather than leaving it open.

The placement argument is also load-bearing and I would not want it lost: the fetch-and-verify body was extracted from action.yml so the security-critical checksum verification has one testable implementation. Inlining it back would restore duplicate-copy drift.

Verified

The ADR-0007 link fix resolves. 0007-manifest-commit-lifecycle.md → 0007-manifest-commit-direct-push.md, and the target exists in the tree.
All 70 relative Markdown links across the 15 touched docs resolve — 0 broken.
The v2/next → main retargeting marks the old branch role as "the original execution plan" rather than deleting it, which keeps a ratified ADR's history readable while stopping it asserting a live branch that is not.

One observation, non-blocking, and I am not asking for a change

§4.1's headline is not self-contained. Read alone — "the terminal state is one bash file" — it invites the check I ran, and the qualifier that makes it true lives a section earlier. A reader doing ls scripts/*.sh finds four and has to go find §3 to reconcile.

Carrying workflow-invoked into §4.1's first sentence would make the section stand on its own. I am not asking you to enumerate the three pending scripts there: an ADR records a decision, not an inventory, and a current-count in a decision record goes stale on the next merge — which is the failure mode this whole PR is repairing.

SCOPE

I verified the workflow-invocation claim, the link fix, and that every relative Markdown link resolves. I did not read the v1.0.0/v2-next retargeting for semantic correctness across all 15 files — I checked that the links work and spot-read the ADR-0009 and VERSIONING diffs, not that every retargeted sentence says the right thing about v1. That is a larger read than the claim I was asked to check, and it is where a second pair of eyes would add most.

**APPROVED @ `fab53aebe2e3dc5e2fd04220da0a46d8edfec9b0`** — 9/9 required contexts green (asserted individually), behind base 0. The load-bearing claim is precisely scoped and I checked the scoping rather than the headline. ## The claim I went after, and it holds §4.1 says *"The terminal state is **one bash file, 171 lines, bootstrap only**: `scripts/fetch-rt.sh`."* **Main has four scripts today**, so I expected this to be an overclaim. It is not — the qualifier in §3 does the work: > *"the **workflow-invoked** shell substrate exits — no v1.x-shell maintenance window. The one residual is the bootstrap fetcher named in §4.1."* **Measured, with the comment-vs-code distinction done properly:** ``` refs OUTSIDE any comment (# stripped mid-line) scripts/fetch-rt.sh 8 ← RT_INSTALL_DIR="$DIR" bash scripts/fetch-rt.sh scripts/repin.sh 0 setup-bump-labels.sh 0 lib/forgejo-api.sh 0 ``` `fetch-rt.sh` is the **only** script any workflow actually runs. The other three appear in workflows solely inside comments — `# … auto-updated by rt prep / repin.sh`, `# See scripts/lib/forgejo-api.sh for the …`. So *"workflow-invoked"* is not softening language, it is the exact predicate that makes the sentence true. *(My first pass counted repin.sh at 5 "executable refs" because I stripped only lines **starting** with `#`, not trailing comments. Control on the corrected version: 7 lines still contain `bash`, so the strip did not eat everything.)* ## §4.1's reasoning is the right kind **The circularity is a construction limit, not an effort estimate**, and the ADR says so in those words: porting `fetch-rt.sh` to `rt` would require `rt` to already be installed, which is the condition the file exists to create. That converts *"zero bash eventually"* from a promise nobody can keep into a bounded, explained residual — and it gives the retirement condition (`a distro package, a container image, a runner image that bakes rt in`) rather than leaving it open. The placement argument is also load-bearing and I would not want it lost: the fetch-and-verify body was extracted from `action.yml` so the **security-critical checksum verification** has one testable implementation. Inlining it back would restore duplicate-copy drift. ## Verified - **The ADR-0007 link fix resolves.** `0007-manifest-commit-lifecycle.md` → `0007-manifest-commit-direct-push.md`, and the target exists in the tree. - **All 70 relative Markdown links across the 15 touched docs resolve — 0 broken.** - The `v2/next` → `main` retargeting marks the old branch role as *"the original execution plan"* rather than deleting it, which keeps a ratified ADR's history readable while stopping it asserting a live branch that is not. ## One observation, non-blocking, and I am not asking for a change **§4.1's headline is not self-contained.** Read alone — *"the terminal state is one bash file"* — it invites the check I ran, and the qualifier that makes it true lives a section earlier. A reader doing `ls scripts/*.sh` finds four and has to go find §3 to reconcile. Carrying *workflow-invoked* into §4.1's first sentence would make the section stand on its own. I am **not** asking you to enumerate the three pending scripts there: an ADR records a decision, not an inventory, and a current-count in a decision record goes stale on the next merge — which is the failure mode this whole PR is repairing. ## SCOPE I verified the workflow-invocation claim, the link fix, and that every relative Markdown link resolves. **I did not read the v1.0.0/v2-next retargeting for semantic correctness across all 15 files** — I checked that the links work and spot-read the ADR-0009 and VERSIONING diffs, not that every retargeted sentence says the right thing about v1. That is a larger read than the claim I was asked to check, and it is where a second pair of eyes would add most.

bosun force-pushed i/778-document-bootstrap-bash-residual from fab53aebe2

build-c4 / build (pull_request) Successful in 23s

Details

check-self-bootstrap / check (pull_request) Successful in 5s

Details

fragment-check / toolkit-self gate (PR's own rt) (pull_request) Successful in 5s

Details

fragment-check / changelog fragment-kind (pull_request) Successful in 7s

Details

fragment-check / check (pull_request) Successful in 0s

Details

go-ci / lint + build + test (pull_request) Successful in 26s