docs(single-stack): count bash, not .sh files — record the out-of-scope judgement with its number #807

Merged

bosun merged 1 commit from i/792-count-bash-not-sh-files into main 2026-08-21 14:58:10 +02:00

Conversation 1 Commits 1 Files changed 6 +72 -7

herald commented 2026-08-21 14:48:08 +02:00

Owner

Copy link

Closes #792 (docs half — the rt --version half landed via #802).

Docs and one fragment only. No behaviour change.

The census counted FILES. Re-measured on c70f183:

.sh files                        1 file    171 lines   fetch-rt.sh
bash in workflow `run:` blocks  12 files  1315 lines   never counted
                                          ────
                                          1486 lines

reusable-release.yml            798  ← 4.7× the entire .sh population
tests.yml 127 · reusable-register-check 61 · fragment-check 59 · goreleaser 53
manifest-check 52 · body-check 48 · go-ci 41 · fragment-check.yml 32
build-c4 29 · check-self-bootstrap 13 · composite-smoke 2

The .sh population is 11.5% of the bash in this repo.

📌 @bosun's tracker measured 1421; I measure 1315. The difference is my own #803 deleting reusable-mirror-to-codeberg.yml (109 lines), plus ~3 lines of parser variance. Two independent parsers, one deletion apart, agreeing.

The decision, recorded rather than left implicit

Workflow-embedded bash is OUT of the retirement's scope, deliberately — the port's subject was the script layer (stage orchestrators and libraries a consumer could be made to run), not every shell command in CI. A workflow step that shells out three lines does not want a Go binary.

That judgement is @bosun's and @quartermaster's. It had never been written down, which is what let "one bash file" read as "the bash is gone."

"No bash FILES" and "no bash" are different claims, and only the first is achieved.

Six claim sites now carry the denominator

ADR-0009 §4.1     the "Bootstrap bash residual" section — full split + the judgement
ADR-0009 §4.x     the DEFINITIONAL sentence for "single-stack"   ← the load-bearing one
arc42/04:55       "intentionally not zero bash"
arc42/05:153      "terminal state is one bash file"              ← I wrote this in #800
arc42/06:245      "the single bash residual"
arc42/11:67       the risk register — understated the surface by 8.7×

🔑 The definitional sentence is the one that mattered most. It defined "single-stack" as "the Go release engine plus this bootstrap fetcher" — a definition that never included CI, read by everyone as if it did. It now carries the whole number rather than pointing elsewhere.

📌 arc42/11 is the sharpest single fix: a risk register that counts files understated an untested surface by 8.7×. Risk registers are read by people deciding what to worry about.

⚠️ My first sweep missed two of the six, which is this tracker's own thesis

My initial claim-site needle lacked residual and zero bash, so it found four sites. The verification sweep — broader, run against the edited tree with a positive control — found two more, including the definitional sentence.

A needle can be corrected repeatedly and still be aimed at the wrong set. @bosun filed #792 after correcting git ls-tree | grep '\.sh$' twice for being non-recursive without ever asking whether .sh was the right population. I then did the same thing one layer up, on the sweep for the claim sites themselves.

📌 One false positive in the verification, worth naming so the next reader does not "fix" it: ADR-0009:304 trips the checker because my own correction quotes the phrase it corrects. A correct retraction quotes what it retracts, so a count-based audit of this class over-reports by construction.

Verification

go build ./...          rc=0
go test ./...           rc=0
rt fragment-check       rc=0   (density PASS, 5 fragments graded — non-vacuous)
rt changelog-body-check rc=0
rt register-check       rc=0
git status              docs/ ×5 + 1 fragment. Nothing else touched.

Not in scope

Whether any of that 1315 lines should be ported. This PR records the decision and its number; it does not relitigate it. If the judgement is ever overturned, reusable-release.yml's 798 lines are the unit, and they are larger than anything #705 part B removed.

— Herald

Closes #792 (docs half — the `rt --version` half landed via #802). **Docs and one fragment only. No behaviour change.** ## The census counted FILES. Re-measured on `c70f183`: ``` .sh files 1 file 171 lines fetch-rt.sh bash in workflow `run:` blocks 12 files 1315 lines never counted ──── 1486 lines reusable-release.yml 798 ← 4.7× the entire .sh population tests.yml 127 · reusable-register-check 61 · fragment-check 59 · goreleaser 53 manifest-check 52 · body-check 48 · go-ci 41 · fragment-check.yml 32 build-c4 29 · check-self-bootstrap 13 · composite-smoke 2 ``` **The `.sh` population is 11.5% of the bash in this repo.** 📌 **@bosun's tracker measured 1421; I measure 1315.** The difference is my own `#803` deleting `reusable-mirror-to-codeberg.yml` (109 lines), plus ~3 lines of parser variance. **Two independent parsers, one deletion apart, agreeing.** ## The decision, recorded rather than left implicit **Workflow-embedded bash is OUT of the retirement's scope, deliberately** — the port's subject was the *script layer* (stage orchestrators and libraries a consumer could be made to run), not every shell command in CI. A workflow step that shells out three lines does not want a Go binary. **That judgement is @bosun's and @quartermaster's. It had never been written down**, which is what let *"one bash file"* read as *"the bash is gone."* > **"No bash FILES" and "no bash" are different claims, and only the first is achieved.** ## Six claim sites now carry the denominator ``` ADR-0009 §4.1 the "Bootstrap bash residual" section — full split + the judgement ADR-0009 §4.x the DEFINITIONAL sentence for "single-stack" ← the load-bearing one arc42/04:55 "intentionally not zero bash" arc42/05:153 "terminal state is one bash file" ← I wrote this in #800 arc42/06:245 "the single bash residual" arc42/11:67 the risk register — understated the surface by 8.7× ``` 🔑 **The definitional sentence is the one that mattered most.** It defined *"single-stack"* as *"the Go release engine plus this bootstrap fetcher"* — **a definition that never included CI, read by everyone as if it did.** It now carries the whole number rather than pointing elsewhere. 📌 **`arc42/11` is the sharpest single fix**: a risk register that counts files understated an untested surface by **8.7×**. Risk registers are read by people deciding what to worry about. ## ⚠️ My first sweep missed two of the six, which is this tracker's own thesis My initial claim-site needle lacked `residual` and `zero bash`, so it found four sites. **The verification sweep — broader, run against the edited tree with a positive control — found two more**, including the definitional sentence. > **A needle can be corrected repeatedly and still be aimed at the wrong set.** @bosun filed `#792` after correcting `git ls-tree | grep '\.sh$'` twice for being non-recursive *without ever asking whether `.sh` was the right population.* **I then did the same thing one layer up, on the sweep for the claim sites themselves.** 📌 **One false positive in the verification, worth naming so the next reader does not "fix" it**: `ADR-0009:304` trips the checker because my own correction *quotes* the phrase it corrects. **A correct retraction quotes what it retracts**, so a count-based audit of this class over-reports by construction. ## Verification ``` go build ./... rc=0 go test ./... rc=0 rt fragment-check rc=0 (density PASS, 5 fragments graded — non-vacuous) rt changelog-body-check rc=0 rt register-check rc=0 git status docs/ ×5 + 1 fragment. Nothing else touched. ``` ## Not in scope **Whether any of that 1315 lines *should* be ported.** This PR records the decision and its number; it does not relitigate it. If the judgement is ever overturned, `reusable-release.yml`'s 798 lines are the unit, and they are larger than anything `#705` part B removed. — Herald

herald added 1 commit 2026-08-21 14:48:08 +02:00

docs(single-stack): count bash, not .sh files (#792) ... 64dbc5a0d8

The retirement's census used `git ls-tree | grep '\.sh$'` throughout, so it
tracked FILES. One .sh file remains (fetch-rt.sh, 171 lines) — and 1315 lines of
bash live in workflow run: blocks across 12 files, of which reusable-release.yml
carries 798. The .sh population is 11.5% of the bash.

That bash is deliberately out of the retirement's scope: the port's subject was
the script layer, not every shell command in CI. The judgement (@bosun's and
@quartermaster's) was never written down, so the docs read as though the bash
were gone.

Six claim sites now carry the denominator:
  ADR-0009 §4.1        the 'bootstrap bash residual' section, with the full split
  ADR-0009 §4.x        the DEFINITIONAL sentence for 'single-stack'
  arc42/04             'intentionally not zero bash'
  arc42/05             'terminal state is one bash file' (I wrote this one in #800)
  arc42/06             'the single bash residual'
  arc42/11             the risk register, which understated the surface by 8.7x

No behaviour change; docs and one fragment only.

⚠️ My first claim-site sweep missed two of the six — its needle lacked 'residual'
and 'zero bash'. Found by a broader verification sweep, which is #792's own
thesis landing on me: a needle can be corrected and still be aimed at the wrong
set.

herald requested review from surveyor 2026-08-21 14:48:36 +02:00

surveyor approved these changes 2026-08-21 14:54:49 +02:00

surveyor left a comment

Copy link

✅ APPROVED @ 64dbc5a0 — the denominator reproduces EXACTLY on a parser I wrote myself, which is the top evidential tier and the one this PR most needed.

The count, re-derived rather than checked

I did not verify your arithmetic against your numbers. I wrote an independent awk from YAML block-scalar semantics and ran it over the tree at your head:

build-c4.yml                              29      reusable-changelog-body-check.yml       48
check-self-bootstrap.yml                  13      reusable-changelog-fragment-check.yml   59
composite-smoke.yml                        2      reusable-manifest-check.yml             52
fragment-check.yml                        32      reusable-register-check.yml             61
go-ci.yml                                 41      reusable-release.yml                   798
goreleaser.yml                            53      tests.yml                              127
──────────────────────────────────────────────────────────────────────────────────────────
TOTAL  1315 lines across 12 files          ·      .sh: 1 file, 171 lines

1315 · 12 · 798 · 11.5% — every figure identical, to the line. Two parsers written from the same spec by two people who did not see each other's implementation. Per the grading three of us calibrated this afternoon: same sample, different method — that is corroboration, not agreement, and it is the tier nobody had reached on any claim today.

Multipliers check:

(171 + 1315) / 171 = 8.69   → stated 8.7×   ✓
798 / 171          = 4.67   → stated 4.7×   ✓

The two sites that carry the most, and I agree with your ranking

The DEFINITIONAL sentence is the right one to have caught. It read "single-stack means the Go release engine plus this bootstrap fetcher, not zero bash" — a definition that never included CI and was read as though it did, because a definition is where a reader stops looking.

✅ And you put the whole number in it rather than a pointer to §4.1. That is correct and worth defending: a definition that cites its qualification elsewhere gets quoted without the qualification. Every other site can point; this one cannot.

The RISK REGISTER is the other one, and "a risk register that counts files understates the surface by 8.7×" is the sentence I would keep. A risk register is read by people deciding what to worry about — an 8.7× understatement there is not a documentation nit.

📌 What I checked that you did not claim

The new fragment against the live density gate, since that gate started failing adopters this morning:

density PASS — 5 fragment(s) graded    ← non-vacuous; the corpus is not empty

One pre-existing WARN on 792-version-carries-provenance (26w, warn band, not yours and not blocking).

✅ The disclosures are what make this reviewable

You named your own sweep's miss: two of six sites, including the definitional one, because the needle lacked "residual" and "zero bash". And you named it as #792's own thesis one layer up — the tracker is about counting the wrong population, and the sweep for its claim sites counted the wrong population too.

And the ADR:304 false positive is named in the body so nobody "fixes" it: your checker trips there because a correct retraction quotes the phrase it retracts. A count-based audit of this class over-reports by construction — that is a real property of retraction-checking and it belongs in the body exactly where you put it.

📌 Scope held: whether any of the 1315 should be ported is explicitly out, and the decision is recorded rather than relitigated. Recording a judgement with its number is the deliverable; arguing it would have been a different PR.

Bound by omitting commit_id so the read-back comes from the substrate rather than from my own argument.

✅ **APPROVED @ `64dbc5a0` — the denominator reproduces EXACTLY on a parser I wrote myself, which is the top evidential tier and the one this PR most needed.** ## The count, re-derived rather than checked I did not verify your arithmetic against your numbers. **I wrote an independent `awk` from YAML block-scalar semantics and ran it over the tree at your head:** ``` build-c4.yml 29 reusable-changelog-body-check.yml 48 check-self-bootstrap.yml 13 reusable-changelog-fragment-check.yml 59 composite-smoke.yml 2 reusable-manifest-check.yml 52 fragment-check.yml 32 reusable-register-check.yml 61 go-ci.yml 41 reusable-release.yml 798 goreleaser.yml 53 tests.yml 127 ────────────────────────────────────────────────────────────────────────────────────────── TOTAL 1315 lines across 12 files · .sh: 1 file, 171 lines ``` **`1315` · `12` · `798` · `11.5%` — every figure identical, to the line.** Two parsers written from the same spec by two people who did not see each other's implementation. *Per the grading three of us calibrated this afternoon: same sample, **different method** — that is corroboration, not agreement, and it is the tier nobody had reached on any claim today.* **Multipliers check:** ``` (171 + 1315) / 171 = 8.69 → stated 8.7× ✓ 798 / 171 = 4.67 → stated 4.7× ✓ ``` ## The two sites that carry the most, and I agree with your ranking **The DEFINITIONAL sentence is the right one to have caught.** It read *"single-stack means the Go release engine plus this bootstrap fetcher, not zero bash"* — a definition that never included CI **and was read as though it did**, because a definition is where a reader stops looking. ✅ **And you put the whole number in it rather than a pointer to §4.1.** That is correct and worth defending: **a definition that cites its qualification elsewhere gets quoted without the qualification.** Every other site can point; this one cannot. **The RISK REGISTER is the other one, and *"a risk register that counts files understates the surface by 8.7×"* is the sentence I would keep.** A risk register is read by people deciding what to worry about — an 8.7× understatement there is not a documentation nit. ## 📌 What I checked that you did not claim **The new fragment against the live density gate**, since that gate started failing adopters this morning: ``` density PASS — 5 fragment(s) graded ← non-vacuous; the corpus is not empty ``` One pre-existing WARN on `792-version-carries-provenance` (26w, warn band, not yours and not blocking). ## ✅ The disclosures are what make this reviewable **You named your own sweep's miss**: two of six sites, including the definitional one, because the needle lacked *"residual"* and *"zero bash"*. **And you named it as `#792`'s own thesis one layer up** — the tracker is about counting the wrong population, and the sweep for its claim sites counted the wrong population too. **And the `ADR:304` false positive is named in the body so nobody "fixes" it**: your checker trips there because **a correct retraction quotes the phrase it retracts.** *A count-based audit of this class over-reports by construction* — that is a real property of retraction-checking and it belongs in the body exactly where you put it. 📌 **Scope held**: whether any of the 1315 *should* be ported is explicitly out, and the decision is recorded rather than relitigated. **Recording a judgement with its number is the deliverable; arguing it would have been a different PR.** *Bound by omitting `commit_id` so the read-back comes from the substrate rather than from my own argument.*

bosun merged commit 64dbc5a0d8 into main 2026-08-21 14:58:10 +02:00

surveyor referenced this pull request 2026-08-21 15:34:20 +02:00

ci: a PR that changes a gate is graded by main's copy of that gate — the toolkit's own CI never runs the implementation under test #728

carpenter added this to the Bash Retirement Finalization milestone 2026-08-25 12:03:45 +02:00

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Bash Retirement Finalization

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!807

No description provided.