feat(check-self-bootstrap): wrapper toolkit_ref alignment-enforcement (the single-ref blind-spot worked-instance from #162)

quartermaster commented

2026-06-27 02:34:45 +02:00

Owner

Why

The first two-wrapper re-pin (#162, v0.11.1-rc.1) surfaced a worked-instance of the AGENTS.md section 2.3 single-ref blind-spot in check-self-bootstrap.sh. Quoted from #162's "worked catch":

Initial sed pass missed manifest-check.yml's toolkit_ref: input — I sed'd uses: lines only. check-self-bootstrap.sh's single-PINNED_REF logic (reads only release.yml's toolkit_ref) wouldn't have caught this drift. Self-corrected in-PR via a follow-up grep.

Surveyor's #162 framing made the scope concrete (review f0a7):

The DOUBLING is the new risk: first re-pin with 4 lines across 2 wrappers. A sed targeting uses: only silently leaves toolkit_ref:; check-self-bootstrap.sh reads ONLY release.yml's toolkit_ref as PINNED_REF -> can't see a stale manifest-check.yml toolkit_ref. Manual grep caught it - shouldn't depend on remembering to grep.

So the practice failure is: cross-wrapper toolkit_ref alignment drift is invisible to the structural backstop.

Scope (per Surveyor's two-tier split)

Tier 1 — Alignment-enforcement (THIS TRACKER)

Add a wrapper-ALIGNMENT check FIRST: assert all consumer-wrapper toolkit_ref values are EQUAL across all .forgejo/workflows/*.yml consumer wrappers.

Directly catches the #162 sed-miss class (uses:-only sed leaves toolkit_ref: stale on the OTHER wrapper)
ENFORCES the single-ref alignment that AGENTS.md section 2.3 currently only DOCUMENTS
Narrower scope than full multi-ref-aware: doesn't permit divergence; rejects it loudly
Worked-instance fix anchored in the actual bug (#162)

Tier 2 — Multi-ref-aware (NOT this tracker; section 2.3 break-condition evolution)

Reserved for the case where the toolkit deliberately pins reusables to different refs (e.g., _release.yml@vA + _manifest-check.yml@vB). That's the AGENTS.md section 2.3 documented design point. Not needed today — single-ref alignment is the invariant we want to PRESERVE, not soften.

Implementation surface (Tier 1)

scripts/check-self-bootstrap.sh:

Discover all consumer-wrapper YAML files: .forgejo/workflows/*.yml minus the underscore-prefixed reusables (_release.yml, _manifest-check.yml).
For each, extract toolkit_ref: (the value passed to the reusable's with: block — distinct from the uses: ...@<ref> ref).
Assert all extracted toolkit_ref values are equal. Fail loud with the divergent values if not.
Use the asserted-equal value as PINNED_REF going forward (current logic continues from there).

Also extract @<ref> from each uses: clause and assert it equals the asserted toolkit_ref. This catches the case where uses: and toolkit_ref: drift on the SAME wrapper file (release.yml:58 shifted to v0.11.1-rc.1 while release.yml:60 stays at v0.10.4-rc.1).

So the matrix of drift catches becomes (for N wrappers, each with uses: + toolkit_ref: = 2N surfaces):

Drift shape	Pre-#XXX	Post-#XXX
`release.yml uses:` ≠ pinned content	catches	catches
`release.yml toolkit_ref:` ≠ pinned content	catches (read directly)	catches
`release.yml uses:` ≠ `release.yml toolkit_ref:`	misses	catches (alignment)
`manifest-check.yml uses:` ≠ pinned ref	misses	catches (alignment)
`manifest-check.yml toolkit_ref:` ≠ pinned ref	misses (the #162 catch)	catches (alignment)

Bats coverage

Add bats fixtures that demonstrate each NEW catch surface:

Misaligned uses: vs toolkit_ref: on same wrapper -> FAIL
Misaligned toolkit_ref: across two wrappers -> FAIL with both values shown
All-aligned -> OK (regression guard)

Composition with AGENTS.md sections 2 + 11

section 2: this DEEPENS the mechanism-of-touch backstop with alignment-as-invariant
section 2.3 design point on multi-ref-aware: REVISED — alignment-enforcement is the v1 step; multi-ref-aware (intentional divergence) is the documented break-condition evolution beyond it
AGENTS.md should be updated with the new TWO-stage framing (alignment-enforcement -> multi-ref-aware) in the same PR

What this tracker does NOT do

Does NOT enable multi-ref-aware logic (deliberately deferred per Surveyor's scope split)
Does NOT change the compose-script equality check (the script's main responsibility — comparing HEAD content vs pinned ref's content — stays as-is)
Does NOT add a regression guard for ADDING a new consumer wrapper (the auto-discovery via .forgejo/workflows/*.yml minus underscore-prefixed files handles that case automatically)

Refs

Worked instance: PR #162 (re-pin @v0.11.1-rc.1; sed missed manifest-check.yml's toolkit_ref:)
Surveyor review f0a7 (framed the two-tier scope split — alignment-enforcement now, multi-ref-aware reserved)
AGENTS.md section 2.3 (single-ref documented assumption, currently unenforced)
#124 (the backstop being extended)

## Why The first two-wrapper re-pin (#162, v0.11.1-rc.1) surfaced a worked-instance of the AGENTS.md section 2.3 single-ref blind-spot in `check-self-bootstrap.sh`. Quoted from #162's "worked catch": > Initial sed pass missed `manifest-check.yml`'s `toolkit_ref:` input — I sed'd `uses:` lines only. check-self-bootstrap.sh's single-`PINNED_REF` logic (reads only `release.yml`'s `toolkit_ref`) wouldn't have caught this drift. Self-corrected in-PR via a follow-up grep. Surveyor's #162 framing made the scope concrete (review f0a7): > The DOUBLING is the new risk: first re-pin with 4 lines across 2 wrappers. A sed targeting `uses:` only silently leaves `toolkit_ref:`; check-self-bootstrap.sh reads ONLY release.yml's toolkit_ref as PINNED_REF -> can't see a stale manifest-check.yml toolkit_ref. Manual grep caught it - shouldn't depend on remembering to grep. So the practice failure is: cross-wrapper `toolkit_ref` **alignment** drift is invisible to the structural backstop. ## Scope (per Surveyor's two-tier split) ### Tier 1 — Alignment-enforcement (THIS TRACKER) Add a wrapper-ALIGNMENT check FIRST: assert all consumer-wrapper `toolkit_ref` values are EQUAL across all `.forgejo/workflows/*.yml` consumer wrappers. - Directly catches the #162 sed-miss class (`uses:`-only sed leaves `toolkit_ref:` stale on the OTHER wrapper) - ENFORCES the single-ref alignment that AGENTS.md section 2.3 currently only DOCUMENTS - Narrower scope than full multi-ref-aware: doesn't permit divergence; rejects it loudly - Worked-instance fix anchored in the actual bug (#162) ### Tier 2 — Multi-ref-aware (NOT this tracker; section 2.3 break-condition evolution) Reserved for the case where the toolkit deliberately pins reusables to different refs (e.g., `_release.yml@vA` + `_manifest-check.yml@vB`). That's the AGENTS.md section 2.3 documented design point. Not needed today — single-ref alignment is the invariant we want to PRESERVE, not soften. ## Implementation surface (Tier 1) `scripts/check-self-bootstrap.sh`: 1. Discover all consumer-wrapper YAML files: `.forgejo/workflows/*.yml` minus the underscore-prefixed reusables (`_release.yml`, `_manifest-check.yml`). 2. For each, extract `toolkit_ref:` (the value passed to the reusable's `with:` block — distinct from the `uses: ...@<ref>` ref). 3. Assert all extracted `toolkit_ref` values are equal. Fail loud with the divergent values if not. 4. Use the asserted-equal value as `PINNED_REF` going forward (current logic continues from there). Also extract `@<ref>` from each `uses:` clause and assert it equals the asserted `toolkit_ref`. This catches the case where `uses:` and `toolkit_ref:` drift on the SAME wrapper file (`release.yml:58` shifted to v0.11.1-rc.1 while `release.yml:60` stays at v0.10.4-rc.1). So the matrix of drift catches becomes (for N wrappers, each with `uses:` + `toolkit_ref:` = 2N surfaces): | Drift shape | Pre-#XXX | Post-#XXX | |---|---|---| | `release.yml uses:` ≠ pinned content | catches | catches | | `release.yml toolkit_ref:` ≠ pinned content | catches (read directly) | catches | | `release.yml uses:` ≠ `release.yml toolkit_ref:` | misses | **catches (alignment)** | | `manifest-check.yml uses:` ≠ pinned ref | misses | **catches (alignment)** | | `manifest-check.yml toolkit_ref:` ≠ pinned ref | **misses (the #162 catch)** | **catches (alignment)** | ## Bats coverage Add bats fixtures that demonstrate each NEW catch surface: - Misaligned `uses:` vs `toolkit_ref:` on same wrapper -> FAIL - Misaligned `toolkit_ref:` across two wrappers -> FAIL with both values shown - All-aligned -> OK (regression guard) ## Composition with AGENTS.md sections 2 + 11 - section 2: this DEEPENS the mechanism-of-touch backstop with alignment-as-invariant - section 2.3 design point on multi-ref-aware: REVISED — alignment-enforcement is the v1 step; multi-ref-aware (intentional divergence) is the documented break-condition evolution beyond it - AGENTS.md should be updated with the new TWO-stage framing (alignment-enforcement -> multi-ref-aware) in the same PR ## What this tracker does NOT do - Does NOT enable multi-ref-aware logic (deliberately deferred per Surveyor's scope split) - Does NOT change the compose-script equality check (the script's main responsibility — comparing HEAD content vs pinned ref's content — stays as-is) - Does NOT add a regression guard for ADDING a new consumer wrapper (the auto-discovery via `.forgejo/workflows/*.yml` minus underscore-prefixed files handles that case automatically) ## Refs - Worked instance: PR #162 (re-pin @v0.11.1-rc.1; sed missed manifest-check.yml's `toolkit_ref:`) - Surveyor review f0a7 (framed the two-tier scope split — alignment-enforcement now, multi-ref-aware reserved) - AGENTS.md section 2.3 (single-ref documented assumption, currently unenforced) - #124 (the backstop being extended)

quartermaster referenced this issue from a commit

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

feat: auto-prune superseded -rc.N tags after cut (closes #153)

Rows
Columns

feat(check-self-bootstrap): wrapper toolkit_ref alignment-enforcement (the single-ref blind-spot worked-instance from #162) #163

Why