fix(recovery): a colliding example version, rt jargon, and a silent second stranded cut #1138

New issue

Closed

opened 2026-09-04 18:34:18 +02:00 by bosun · 0 comments

bosun commented

2026-09-04 18:34:18 +02:00

Owner

Three small things in the recovery workflow, found by reading it as an adopter would. Two are wording, one is a real gap.

1. A colliding example version

v0.57.0 appears twice in reusable-recover-pending-cut.yml with unrelated meanings:

:34   'The pending version to recover ... (e.g. 0.57.0)'   an example
:88   BUILD_BAKED_TOOLKIT_REF: 'v0.57.0'                   HARD-WIRED — the baked toolkit pin

A careful reader cannot tell from the file which one binds, and reasonably concludes the input is hard-wired. It is not — version: ${{ inputs.version }} is plumbed correctly. Use an example that cannot collide (1.2.3).

2. `rt` is jargon in adopter-facing text

The input descriptions are read by someone who installed the toolkit, not by us. Name the tool: "the version release-toolkit reports as pending", not "what rt reports".

3. A second stranded cut is silent — the real gap

The pending-version predicate reads the top-most released section above the manifest, so the verb folds exactly one. If two versions are stranded, the second stays put and nothing says so. The operator has no reason to suspect it, and it surfaces later as a fresh pending_cut block on their next release.

After a successful fold, re-check and report it — "one more pending version remains, run again".

The no-work case already refuses well and needs no change:

this is not the state recovery (B) repairs: decide reports mode=update,
not blocked/pending_cut. Nothing to fold back

AC

the example version in both twins cannot be confused with the baked toolkit ref
adopter-facing input descriptions name release-toolkit rather than rt — scope: input descriptions only. Two error messages still name rt decide and rt recover-pending-cut; those are commands an adopter can run, not jargon, and stripping them would make the errors less useful.
after a successful fold, a remaining stranded version is detected and named in the output — in the remaining_pending_version output, the PR body, and a ::warning::. A re-grade that cannot grade is disclosed as unknown, not as clean.
an arm with two stranded versions: the first run folds one and announces the second; the second run folds it and does not — partially, and the split is stated rather than smoothed over. TestFoldBackRecoversExactlyOneStrandedSection measures the fold half end-to-end: two stranded sections, folded twice, heading sequence asserted at each step, plus a third-fold control returning ErrSectionNotFound. The announces half is covered structurally by the bats arm (the re-grade runs after the fold and reaches the body and the output) — not behaviourally. A full two-run pass through the workflow itself is not exercised here and would need a live runner.
the no-work refusal is unchanged — verified from the diff: no line of git diff origin/main...HEAD touches either refusal.

Anchor

Operator review of #1135's merged workflow, 2026-09-04. Item 1 found via a wrong mechanism — the input was assumed hard-wired — which is itself the evidence that the collision misleads.

Three small things in the recovery workflow, found by reading it as an adopter would. Two are wording, one is a real gap. ## 1. A colliding example version `v0.57.0` appears twice in `reusable-recover-pending-cut.yml` with unrelated meanings: ``` :34 'The pending version to recover ... (e.g. 0.57.0)' an example :88 BUILD_BAKED_TOOLKIT_REF: 'v0.57.0' HARD-WIRED — the baked toolkit pin ``` A careful reader cannot tell from the file which one binds, and reasonably concludes the input is hard-wired. It is not — `version: ${{ inputs.version }}` is plumbed correctly. Use an example that cannot collide (`1.2.3`). ## 2. `rt` is jargon in adopter-facing text The input descriptions are read by someone who installed the toolkit, not by us. Name the tool: *"the version release-toolkit reports as pending"*, not *"what rt reports"*. ## 3. A second stranded cut is silent — the real gap The pending-version predicate reads the **top-most** released section above the manifest, so the verb folds exactly one. If two versions are stranded, the second stays put and nothing says so. The operator has no reason to suspect it, and it surfaces later as a fresh `pending_cut` block on their next release. After a successful fold, re-check and report it — *"one more pending version remains, run again"*. The no-work case already refuses well and needs no change: ``` this is not the state recovery (B) repairs: decide reports mode=update, not blocked/pending_cut. Nothing to fold back ``` ## AC - [x] the example version in both twins cannot be confused with the baked toolkit ref - [x] adopter-facing input descriptions name release-toolkit rather than `rt` — **scope:** input descriptions only. Two error messages still name `rt decide` and `rt recover-pending-cut`; those are **commands an adopter can run**, not jargon, and stripping them would make the errors less useful. - [x] after a successful fold, a remaining stranded version is detected and named in the output — in the `remaining_pending_version` output, the PR body, and a `::warning::`. A re-grade that cannot grade is disclosed as **unknown**, not as clean. - [x] an arm with two stranded versions: the first run folds one and announces the second; the second run folds it and does not — **partially, and the split is stated rather than smoothed over.** `TestFoldBackRecoversExactlyOneStrandedSection` measures the fold half end-to-end: two stranded sections, folded twice, heading sequence asserted at each step, plus a third-fold control returning `ErrSectionNotFound`. The **announces** half is covered *structurally* by the bats arm (the re-grade runs after the fold and reaches the body and the output) — **not behaviourally**. A full two-run pass through the workflow itself is not exercised here and would need a live runner. - [x] the no-work refusal is unchanged — verified from the diff: no line of `git diff origin/main...HEAD` touches either refusal. ## Anchor Operator review of #1135's merged workflow, 2026-09-04. Item 1 found via a wrong mechanism — the input was assumed hard-wired — which is itself the evidence that the collision misleads.

bosun added this to the Adoption — usable by a stranger on their own forge milestone

2026-09-04 18:34:18 +02:00

bosun added the

priority/medium

size/S

kind/bug

labels

2026-09-04 18:34:18 +02:00