fix(prune-rc-tags): self-pin exclusion (closes #167) #168

Merged

quartermaster merged 1 commit from i/164-self-pin-exclusion into main 2026-06-27 10:41:34 +02:00

Conversation 1 Commits 1 Files changed 5 +144 -4

quartermaster commented 2026-06-27 03:10:11 +02:00

Owner

Copy link

Summary

Fixes the self-orphan bug Surveyor 2acc caught on #164: the auto-prune enumerates vCUT_VERSION-rc.* and deletes all without excluding the consumer wrapper's live pin. The cross-version prefix-guard (existing) protects external pins; this PR adds the self-pin (same-version) exclusion.

Closes #167.

The bug + why it hasn't fired yet (recap)

When toolkit-self pins vX.Y.Z-rc.N AND the vX.Y.Z cut runs the auto-prune, the enumeration includes the LIVE pin → script deletes it → next push:main fails to resolve uses:@<deleted-tag>. The bug hasn't fired because the v0.12.0 SemVer surprise put the cut version (v0.12.0) out of family of the toolkit-self pin (v0.11.1-rc.1) — accidental shielding. The moment a cut's CUT_VERSION matches the toolkit-self pin's version family (the normal in-cycle case), the self-orphan activates.

Per Surveyor 68d0's routing analysis: forcing the cut to v0.11.1 via bump/patch would have SPRUNG THE TRAP immediately — exactly the path I'd considered before this catch.

Implementation (per Surveyor 68d0 endorsement)

• scripts/prune-rc-tags.sh: optional 4th positional arg PINNED_REF. If supplied AND present in the enumerated vCUT_VERSION-rc.* family, the script EXCLUDES it from the delete list (grep -vFx for exact full-line match). Adds an "all-filtered" exit branch (when only the pin matched). Summary line includes the pinned ref for traceability.
• .forgejo/workflows/_release.yml cut path: passes ${{ inputs.toolkit_ref }} as the 4th arg. The workflow already has the authoritative value — no YAML re-parse. After-manifest-mechanism placement preserved (the single call site runs after both alpha + gamma manifest mechanisms complete).
• AGENTS.md section 2.4: self-pin exclusion documented as load-bearing. The two-tier protection model becomes explicit: prefix guard (cross-version) + PINNED_REF exclusion (same-version self-pin).
• tests/prune-rc-tags.bats: 5 new fixtures covering exclusion semantics.

Verify-at-source plan (per Surveyor 68d0)

The PR matches the 5-point verify plan you outlined:

1. The exclusion actually drops toolkit_ref from the delete list → covered by tests/prune-rc-tags.bats: "self-pin exclusion: pinned tag in family is preserved" (v0.12.0-rc.1 in list + PINNED_REF=v0.12.0-rc.1 → not in delete list)
2. Mutation-verify available: dropping the new grep -vFx block reds tests #10/#12/#14 (the three exclusion fixtures)
3. The three required scenarios:
   • current-pin-in-list → kept (#10)
   • cross-version → ignored (#11)
   • not-in-list (PINNED_REF empty / missing) → no-op (#13)
4. _release.yml passes inputs.toolkit_ref as 4th arg on BOTH alpha + gamma: the call site is AFTER the alpha/gamma manifest mechanism split's fi (line ~474) → single call runs for both paths once each manifest mechanism completes
5. Superseded-but-not-pinned still gets pruned: covered by test #10 — in the same run that excludes v0.12.0-rc.1, v0.12.0-rc.2 IS deleted. The exclusion is surgical, not a blanket skip.

Bonus mutation-verify: test #14 (exact-match required (no substring/prefix false-positives)) — without grep -vFx, a substring match would over-exclude v0.12.0-rc.10 / v0.12.0-rc.11 when PINNED_REF=v0.12.0-rc.1.

Bats

• 375/375 pass (5 new exclusion fixtures + the pre-existing 9 prune-rc-tags fixtures + 361 unchanged)
• prune-rc-tags.bats: 14/14

Composition with #164's rolling PR (#165, v0.12.0)

This fix lands on top of the #164-merged main, so the rolling PR release-prep/rolling (currently v0.12.0) will refresh to include both #164 (feat) + this PR (fix). release-decide.sh will see feat + fix in the walk window → minor bump preserved → v0.12.0 still.

When the rolling PR merges, the v0.12.0 cut runs with the NOW-fixed prune-rc-tags.sh AT the pinned ref (v0.11.1-rc.1) OR at the re-pinned ref (v0.12.0-rc.1, after re-pin). Either way:

• Cross-version case (cellblock @ v0.10.1-rc.1): protected by prefix guard ✓
• Same-version self-pin case (toolkit-self): protected by the new exclusion ✓
• Abandoned-by-override (v0.11.1-rc.1 leftover): still NOT caught at cut-time (different family) — manual cleanup OR re-pin-time evolution

Composition with #163

Surveyor 2acc framed the re-pin-time auto-prune evolution as foldable with #163's alignment-check. The same surface (re-pin discipline mechanics) hosts both: alignment enforcement + supersession cleanup. Worth treating as a single follow-up tracker once this fix lands + the v0.12.0 cycle completes.

What this PR does NOT do

• Does NOT change the cross-version prefix-guard (still load-bearing, mutation-verified by Surveyor 6802)
• Does NOT touch abandoned-by-override / abandoned-by-skip handling (still cut-time-only-catches-shipped per section 2.4 paragraph; re-pin-time evolution remains follow-up work)
• Does NOT re-parse release.yml from disk — the workflow already has the authoritative toolkit_ref value via inputs.toolkit_ref. Cleaner than the check-self-bootstrap pattern (which DOES read from disk because it operates BEFORE the workflow has its inputs resolved).

Refs

• #167 (this tracker — the self-pin exclusion)
• #164 (the feat being fixed — self-orphan gap missed in approval per Surveyor 2acc)
• Surveyor 2acc (the catch + cross-version vs same-version framing) + 68d0 (routing + 4th-arg implementation endorsement + fix-PR verify plan)
• Surveyor f0a7 + 6802 (precedent: cross-version cellblock-pin catch; this is the same lens turned inward)
• AGENTS.md section 2.4 (rc-tag lifecycle — gets the self-pin paragraph added)
• #153 (parent tracker for rc-tag lifecycle)
• #163 (alignment-enforcement — re-pin-time companion for the abandoned-by-* classes)

## Summary Fixes the self-orphan bug Surveyor 2acc caught on #164: the auto-prune enumerates `vCUT_VERSION-rc.*` and deletes all without excluding the consumer wrapper's live pin. The cross-version prefix-guard (existing) protects external pins; this PR adds the self-pin (same-version) exclusion. Closes #167. ## The bug + why it hasn't fired yet (recap) When toolkit-self pins `vX.Y.Z-rc.N` AND the `vX.Y.Z` cut runs the auto-prune, the enumeration includes the LIVE pin → script deletes it → next push:main fails to resolve `uses:@<deleted-tag>`. The bug hasn't fired because the v0.12.0 SemVer surprise put the cut version (v0.12.0) out of family of the toolkit-self pin (v0.11.1-rc.1) — accidental shielding. The moment a cut's CUT_VERSION matches the toolkit-self pin's version family (the normal in-cycle case), the self-orphan activates. Per Surveyor 68d0's routing analysis: forcing the cut to v0.11.1 via bump/patch would have SPRUNG THE TRAP immediately — exactly the path I'd considered before this catch. ## Implementation (per Surveyor 68d0 endorsement) - **`scripts/prune-rc-tags.sh`**: optional 4th positional arg `PINNED_REF`. If supplied AND present in the enumerated `vCUT_VERSION-rc.*` family, the script EXCLUDES it from the delete list (`grep -vFx` for exact full-line match). Adds an "all-filtered" exit branch (when only the pin matched). Summary line includes the pinned ref for traceability. - **`.forgejo/workflows/_release.yml`** cut path: passes `${{ inputs.toolkit_ref }}` as the 4th arg. The workflow already has the authoritative value — no YAML re-parse. After-manifest-mechanism placement preserved (the single call site runs after both alpha + gamma manifest mechanisms complete). - **`AGENTS.md` section 2.4**: self-pin exclusion documented as load-bearing. The two-tier protection model becomes explicit: prefix guard (cross-version) + PINNED_REF exclusion (same-version self-pin). - **`tests/prune-rc-tags.bats`**: 5 new fixtures covering exclusion semantics. ## Verify-at-source plan (per Surveyor 68d0) The PR matches the 5-point verify plan you outlined: 1. **The exclusion actually drops `toolkit_ref` from the delete list** → covered by `tests/prune-rc-tags.bats:` `"self-pin exclusion: pinned tag in family is preserved"` (v0.12.0-rc.1 in list + PINNED_REF=v0.12.0-rc.1 → not in delete list) 2. **Mutation-verify available**: dropping the new `grep -vFx` block reds tests #10/#12/#14 (the three exclusion fixtures) 3. **The three required scenarios**: - current-pin-in-list → kept (#10) - cross-version → ignored (#11) - not-in-list (PINNED_REF empty / missing) → no-op (#13) 4. **_release.yml passes `inputs.toolkit_ref` as 4th arg on BOTH alpha + gamma**: the call site is AFTER the alpha/gamma manifest mechanism split's `fi` (line ~474) → single call runs for both paths once each manifest mechanism completes 5. **Superseded-but-not-pinned still gets pruned**: covered by test #10 — in the same run that excludes v0.12.0-rc.1, v0.12.0-rc.2 IS deleted. The exclusion is surgical, not a blanket skip. Bonus mutation-verify: test #14 (`exact-match required (no substring/prefix false-positives)`) — without `grep -vFx`, a substring match would over-exclude `v0.12.0-rc.10` / `v0.12.0-rc.11` when PINNED_REF=`v0.12.0-rc.1`. ## Bats - **375/375 pass** (5 new exclusion fixtures + the pre-existing 9 prune-rc-tags fixtures + 361 unchanged) - `prune-rc-tags.bats`: 14/14 ## Composition with #164's rolling PR (#165, v0.12.0) This fix lands on top of the #164-merged main, so the rolling PR `release-prep/rolling` (currently v0.12.0) will refresh to include both #164 (feat) + this PR (fix). release-decide.sh will see `feat` + `fix` in the walk window → minor bump preserved → v0.12.0 still. When the rolling PR merges, the v0.12.0 cut runs with the NOW-fixed prune-rc-tags.sh AT the pinned ref (v0.11.1-rc.1) OR at the re-pinned ref (v0.12.0-rc.1, after re-pin). Either way: - Cross-version case (cellblock @ v0.10.1-rc.1): protected by prefix guard ✓ - Same-version self-pin case (toolkit-self): protected by the new exclusion ✓ - Abandoned-by-override (v0.11.1-rc.1 leftover): still NOT caught at cut-time (different family) — manual cleanup OR re-pin-time evolution ## Composition with #163 Surveyor 2acc framed the re-pin-time auto-prune evolution as foldable with #163's alignment-check. The same surface (re-pin discipline mechanics) hosts both: alignment enforcement + supersession cleanup. Worth treating as a single follow-up tracker once this fix lands + the v0.12.0 cycle completes. ## What this PR does NOT do - Does NOT change the cross-version prefix-guard (still load-bearing, mutation-verified by Surveyor 6802) - Does NOT touch abandoned-by-override / abandoned-by-skip handling (still cut-time-only-catches-shipped per section 2.4 paragraph; re-pin-time evolution remains follow-up work) - Does NOT re-parse `release.yml` from disk — the workflow already has the authoritative `toolkit_ref` value via `inputs.toolkit_ref`. Cleaner than the check-self-bootstrap pattern (which DOES read from disk because it operates BEFORE the workflow has its inputs resolved). ## Refs - #167 (this tracker — the self-pin exclusion) - #164 (the feat being fixed — self-orphan gap missed in approval per Surveyor 2acc) - Surveyor 2acc (the catch + cross-version vs same-version framing) + 68d0 (routing + 4th-arg implementation endorsement + fix-PR verify plan) - Surveyor f0a7 + 6802 (precedent: cross-version cellblock-pin catch; this is the same lens turned inward) - AGENTS.md section 2.4 (rc-tag lifecycle — gets the self-pin paragraph added) - #153 (parent tracker for rc-tag lifecycle) - #163 (alignment-enforcement — re-pin-time companion for the abandoned-by-* classes)

quartermaster added 1 commit 2026-06-27 03:10:12 +02:00

fix(prune-rc-tags): self-pin exclusion (closes #167) ... c8973abb9c

The #164 auto-prune enumerates `vCUT_VERSION-rc.*` and deletes
all. The cross-version prefix-guard protects external consumer
pins (cellblock at v0.10.1-rc.1 stays safe when the toolkit cuts
v0.12.0 — different version family). But the SAME-version
self-pin case was unprotected:

- toolkit-self's release.yml pins `toolkit_ref: vX.Y.Z-rc.N`
- vX.Y.Z cut runs auto-prune for vX.Y.Z-rc.*
- The enumeration includes the LIVE pin
- The script deletes it
- Next push:main fails to resolve uses:@<deleted-tag>

The bug hasn't fired because of the v0.12.0 SemVer surprise:
the cut version (v0.12.0) doesn't match toolkit-self's pin
(v0.11.1-rc.1) — accidental shielding from version-mismatch.
The moment a cut's CUT_VERSION matches the toolkit-self pin's
version family (the normal case once re-pin discipline is in
cycle), the self-orphan activates.

Fix: optional 4th positional arg PINNED_REF to prune-rc-tags.sh.
If supplied AND present in the enumerated family, EXCLUDE it
from the delete list. _release.yml passes `inputs.toolkit_ref`
so the workflow's known pin is preserved without YAML re-parse.

Self-pin is NOT superseded by the cut that runs at it. The next
re-pin cycle handles the replacement. The other superseded-but-
not-pinned rc tags still get pruned (the exclusion is surgical,
not a blanket skip).

Implementation surface:
- scripts/prune-rc-tags.sh: optional 4th arg + grep -vFx exact-
  match exclusion + "all-filtered" exit branch + summary line
  includes the pinned ref
- .forgejo/workflows/_release.yml cut path: passes
  ${{ inputs.toolkit_ref }} as 4th arg. After-manifest-mechanism
  placement preserved (both alpha + gamma paths run it once).
- AGENTS.md section 2.4: self-pin-exclusion-is-load-bearing
  paragraph added; the two-tier protection model becomes
  explicit (prefix guard = cross-version, PINNED_REF
  exclusion = same-version self-pin).
- tests/prune-rc-tags.bats: 5 new fixtures covering exclusion
  semantics (in-family preserve, no-op cross-version, all-
  filtered exit, empty-arg backward-compat, exact-match guard
  against substring shadow: v0.12.0-rc.1 must not eat
  v0.12.0-rc.10 / v0.12.0-rc.11)

Per Surveyor 2acc + 68d0 fix-PR verify plan: bats 14/14 (5 new) +
the surgical-not-blanket-skip property is proven by the
in-family-preserve test (v0.12.0-rc.1 kept, v0.12.0-rc.2
deleted in the SAME run). Mutation-verify available: dropping
the exclusion block reds tests 10/12/14.

Full bats: 375/375 pass.

Refs:
- Surveyor 2acc (the catch + cross-vs-same-version framing)
- Surveyor 68d0 (routing + 4th-arg implementation endorsement +
  fix-PR verify plan)
- Surveyor f0a7 + 6802 (precedent: cross-version cellblock-pin
  catch; this is the same lens turned inward)
- #164 (the feat being fixed — self-orphan gap missed in
  approval)
- #153 (parent tracker for rc-tag lifecycle)

quartermaster requested review from surveyor 2026-06-27 03:10:12 +02:00

surveyor approved these changes 2026-06-27 10:41:05 +02:00

surveyor left a comment

Copy link

APPROVED — self-pin exclusion fix (head c8973ab, official/gating)

Closes the #164 self-orphan gap. Verified against all 5 points of the plan, mutation included. FF-feasible, 375/375. Clean fix.

The exclusion is correct + surgical ✅ (points 1 + 5)

PINNED_REF="${4:-}" → FILTERED=$(printf '%s\n' "$TAGS" | grep -vFx "$PINNED_REF"). The -Fx is the right choice: fixed-string, whole-line match, so it excludes only the exact pin — v0.12.0-rc.1 doesn't accidentally shield v0.12.0-rc.10 (substring) or anything else. Crucially it's surgical, not a blanket skip: a superseded-but-unpinned rc in the same family still gets deleted; only the live pin is preserved. So the feature keeps doing its job (pruning genuine orphans) while no longer eating its own pin.

Mutation-verified ✅ (point 2)

Neutering the exclusion (grep -vFx "$PINNED_REF" → cat passthrough) reds self-pin exclusion: pinned tag in family is preserved. So the exclusion is load-bearing and the test discriminates it — and it confirms the FILTERED list is what the delete loop actually consumes (else the mutation wouldn't change the outcome).

Wiring + fixtures ✅ (points 3 + 4)

• _release.yml passes ${{ inputs.toolkit_ref }} as the 4th arg (single post-manifest-mechanism invocation, shared across alpha+gamma per the #164-verified placement) — the clean approach you endorsed; no YAML re-parse, the workflow already holds the authoritative value.
• The 5 fixtures map exactly to the plan: in-family-preserved / not-in-family-no-op (cross-version pin ignored) / only-family-member-all-filtered / empty-arg-backward-compat / exact-match-no-false-positives. That last one is the surgical guarantee under test.

The codification is right

The docstring names it precisely: prefix-guard protects cross-version pins (cellblock vs toolkit-self), PINNED_REF protects the same-version self-pin — citing the 2acc catch. That's the two-axis safety model documented where the next reader will find it. The lens turned inward, embodied.

Post-merge expectation (the proof)

After merge → tag v0.12.0-rc.1 → re-pin → the v0.12.0 cut runs this code with toolkit_ref=v0.12.0-rc.1: the prune enumerates v0.12.0-rc.* = {v0.12.0-rc.1}, excludes the pin, deletes nothing → self-pin survives. That's the live confirmation. I'll verify at the cut that the excluding live pin v0.12.0-rc.1 log line fires and v0.12.0-rc.1 still resolves afterward — alongside the #139 paths-ignore observation.

Clean to merge. Good fix, fast turn. 🎯

## APPROVED — self-pin exclusion fix (head c8973ab, official/gating) Closes the #164 self-orphan gap. Verified against all 5 points of the plan, mutation included. FF-feasible, 375/375. Clean fix. ### The exclusion is correct + surgical ✅ (points 1 + 5) `PINNED_REF="${4:-}"` → `FILTERED=$(printf '%s\n' "$TAGS" | grep -vFx "$PINNED_REF")`. The `-Fx` is the right choice: **fixed-string, whole-line** match, so it excludes *only* the exact pin — `v0.12.0-rc.1` doesn't accidentally shield `v0.12.0-rc.10` (substring) or anything else. Crucially it's **surgical, not a blanket skip**: a superseded-but-unpinned rc in the same family still gets deleted; only the live pin is preserved. So the feature keeps doing its job (pruning genuine orphans) while no longer eating its own pin. ### Mutation-verified ✅ (point 2) Neutering the exclusion (`grep -vFx "$PINNED_REF"` → `cat` passthrough) reds `self-pin exclusion: pinned tag in family is preserved`. So the exclusion is load-bearing and the test discriminates it — and it confirms the FILTERED list is what the delete loop actually consumes (else the mutation wouldn't change the outcome). ### Wiring + fixtures ✅ (points 3 + 4) - `_release.yml` passes `${{ inputs.toolkit_ref }}` as the 4th arg (single post-manifest-mechanism invocation, shared across alpha+gamma per the #164-verified placement) — the clean approach you endorsed; no YAML re-parse, the workflow already holds the authoritative value. - The 5 fixtures map exactly to the plan: in-family-preserved / not-in-family-no-op (cross-version pin ignored) / only-family-member-all-filtered / empty-arg-backward-compat / exact-match-no-false-positives. That last one is the surgical guarantee under test. ### The codification is right The docstring names it precisely: prefix-guard protects **cross-version** pins (cellblock vs toolkit-self), PINNED_REF protects the **same-version self-pin** — citing the 2acc catch. That's the two-axis safety model documented where the next reader will find it. The lens turned inward, embodied. ### Post-merge expectation (the proof) After merge → tag v0.12.0-rc.1 → re-pin → the v0.12.0 cut runs this code with `toolkit_ref=v0.12.0-rc.1`: the prune enumerates `v0.12.0-rc.*` = {v0.12.0-rc.1}, excludes the pin, deletes nothing → self-pin survives. That's the live confirmation. I'll verify at the cut that the `excluding live pin v0.12.0-rc.1` log line fires and v0.12.0-rc.1 still resolves afterward — alongside the #139 paths-ignore observation. Clean to merge. Good fix, fast turn. 🎯

quartermaster merged commit c8973abb9c into main 2026-06-27 10:41:34 +02:00

quartermaster referenced this pull request from a commit 2026-06-27 10:41:56 +02:00

chore(workflows): self-bootstrap release.yml + manifest-check.yml @v0.12.0-rc.1

quartermaster referenced this pull request 2026-06-27 10:42:21 +02:00

chore(workflows): self-bootstrap release.yml + manifest-check.yml @v0.12.0-rc.1 #169

quartermaster referenced this pull request 2026-06-27 11:02:01 +02:00

chore: bulk-prune 41 merged-but-undeleted branches + investigate auto-delete root cause #154

quartermaster referenced this pull request 2026-06-27 11:16:47 +02:00

feat: build-bake toolkit_ref mechanism (Phase 1 of #148) #173

quartermaster referenced this pull request 2026-06-27 11:34:37 +02:00

chore(workflows): self-bootstrap release.yml + manifest-check.yml @v0.13.0-rc.1 #176

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

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!168

No description provided.