docs: refresh ADR-0008 anchor rot + coupled test-strategy refinements (#480) #482

Merged

bosun merged 1 commit from i/480-adr-anchor-refresh into v2/next

2026-07-08 01:47:41 +02:00

engineer commented

2026-07-08 01:03:12 +02:00

Owner

Closes the #480 follow-up. Two coupled parts, sequenced spec-first-then-consumer.

Part 1 — ADR-0008 systemic anchor refresh

#480 was filed to refresh 3 stale line-anchors in ADR-0008 §6 R1/§4c. Verifying at source revealed the rot is systemic — a byte-precise sweep of all 17 file:line anchors in the ADR found 8 stale, driven by source-file growth (not content change) since the ADR was written:

ADR site	was	now
§1 script callsites	`:225,282,288,306,619,632` ("~6")	`:266,349,366,389,407,843,856` (7)
§4 inline-jq manifest	`:312-335`	`:413-436`
§4 tee `$GITHUB_OUTPUT`	`:225`	`:266`
§5 awk paragraph-normalizer	`draft-release.sh:126-156`	`:131-161`
§6 R1 three-actor bake (cut-prep)	`release-prep.sh:541-546`	`:564-569`
§6 R1 three-actor bake (post-cut reset)	`reusable-release.yml:390-395`	`:490-495`
§6 R2 porcelain parse	`repin.sh:76`	`:86`
§6 R5 secrets block	`reusable-release.yml:77-89`	`:72-83`

9 anchors verified CURRENT and left untouched (release-prep.sh:296-332, five build_bake.sh anchors, reusable-release.yml:407/:366/:843).

Per disclose-and-extend: swept the whole anchor category rather than patching only the 3 named — "what I changed" now matches "the ADR is anchor-clean", not "3 of ~8 fixed". No prose/decision content changed; anchors only.

Unblocked by Part 1 (the ADR anchors these reference are now fresh):

§6b: dropped the "rot-magnet" note that hard-coded the now-fixed stale line#s → plain cite (Surveyor flagged it as a rot-magnet).
§1 ASCII constraint: reframed as harness-fidelity (§3b-derived) — explicitly not a §1 adopter-surface element (a consumer never observes log() text); its enforcement mechanism is §3b's oracle byte-match. Added the #149 YAML-lint-security second reason (AGENTS.md:310): ASCII-only is enforced by two independent gates, not one.
§3b: added the run --separate-stderr stream-fidelity caveat (register-check.bats:175) — stream routing (stdout vs stderr) is part of the byte-equivalence surface.

Verification posture

v2/next draws no CI → gate is Surveyor's reproduction of the cited anchors. All anchors verified byte-precise against the v2/next tip (51cef71). Base = v2/next; independent of PR #481 (Arc42) — different files, no overlap.

What this does NOT do

No prose/analysis/decision changes to ADR-0008 — anchors + counts only.
Does not touch the ADR-0008 proposed status or the v2-port decision.

## Refresh ADR-0008 anchor rot + coupled test-strategy refinements Closes the [#480](https://git.frankenbit.de/frankenbit/release-toolkit/issues/480) follow-up. Two coupled parts, sequenced spec-first-then-consumer. ### Part 1 — ADR-0008 systemic anchor refresh #480 was filed to refresh **3** stale line-anchors in ADR-0008 §6 R1/§4c. Verifying at source revealed the rot is **systemic** — a byte-precise sweep of all 17 `file:line` anchors in the ADR found **8 stale**, driven by source-file *growth* (not content change) since the ADR was written: | ADR site | was | now | |----------|-----|-----| | §1 script callsites | `:225,282,288,306,619,632` ("~6") | `:266,349,366,389,407,843,856` (**7**) | | §4 inline-jq manifest | `:312-335` | `:413-436` | | §4 tee `$GITHUB_OUTPUT` | `:225` | `:266` | | §5 awk paragraph-normalizer | `draft-release.sh:126-156` | `:131-161` | | §6 R1 three-actor bake (cut-prep) | `release-prep.sh:541-546` | `:564-569` | | §6 R1 three-actor bake (post-cut reset) | `reusable-release.yml:390-395` | `:490-495` | | §6 R2 porcelain parse | `repin.sh:76` | `:86` | | §6 R5 secrets block | `reusable-release.yml:77-89` | `:72-83` | **9 anchors verified CURRENT and left untouched** (`release-prep.sh:296-332`, five `build_bake.sh` anchors, `reusable-release.yml:407/:366/:843`). Per **disclose-and-extend**: swept the whole anchor category rather than patching only the 3 named — "what I changed" now matches "the ADR is anchor-clean", not "3 of ~8 fixed". No prose/decision content changed; anchors only. ### Part 2 — coupled test-strategy.md refinements (Surveyor review 3731) Unblocked by Part 1 (the ADR anchors these reference are now fresh): - **§6b**: dropped the "rot-magnet" note that hard-coded the now-fixed stale line#s → plain cite (Surveyor flagged it as a rot-magnet). - **§1 ASCII constraint**: reframed as **harness-fidelity** (§3b-derived) — explicitly **not** a §1 adopter-surface element (a consumer never observes `log()` text); its enforcement mechanism is §3b's oracle byte-match. Added the **#149** YAML-lint-**security** second reason (`AGENTS.md:310`): ASCII-only is enforced by two independent gates, not one. - **§3b**: added the `run --separate-stderr` stream-fidelity caveat (`register-check.bats:175`) — stream routing (stdout vs stderr) is part of the byte-equivalence surface. ### Verification posture `v2/next` draws no CI → gate is Surveyor's reproduction of the cited anchors. All anchors verified byte-precise against the `v2/next` tip (`51cef71`). Base = `v2/next`; **independent of PR #481** (Arc42) — different files, no overlap. ### What this does NOT do - No prose/analysis/decision changes to ADR-0008 — anchors + counts only. - Does not touch the ADR-0008 `proposed` status or the v2-port decision.

engineer added 1 commit

2026-07-08 01:03:12 +02:00

docs: refresh ADR-0008 anchor rot + coupled test-strategy refinements (#480 ) 845eeba026

Part 1 — ADR-0008 systemic anchor refresh. The scoped '3 stale anchors' (§6 R1
/§4c) turned out to be ~8 stale anchor-sets once verified at source; a full sweep
(sub-agent-built byte-precise correction table, all 17 anchors checked) found:
- STALE (8, fixed): §1 callsite series :225,282,288,306,619,632 → :266,349,366,
  389,407,843,856 (and count ~6→7); §4 inline-jq :312-335 → :413-436; §4 tee
  GITHUB_OUTPUT :225 → :266; §5 awk-normalizer draft-release.sh:126-156 → :131-161;
  §6 R1 three-actor bake release-prep.sh:541-546 → :564-569 + reusable-release.yml
  :390-395 → :490-495; §6 R2 repin.sh:76 → :86; §6 R5 secrets block :77-89 → :72-83.
- CURRENT (9, untouched): release-prep.sh:296-332, build_bake.sh:84-164/:90-94/:69/
  :144-150/:105, reusable-release.yml:407/:366/:843.
File growth (not content change) drove the drift; disclose-and-extend → swept the
whole category rather than patching only the 3 originally named.

Part 2 — coupled test-strategy.md refinements (Surveyor 3731, now unblocked by the
ADR refresh, spec-first-then-consumer):
- §6b: dropped the rot-magnet note (hard-coded the now-fixed stale line#s) → plain
  cite, since the ADR anchors are refreshed + consistent.
- §1 ASCII constraint: reframed as harness-fidelity (§3b-derived), explicitly NOT a
  §1 adopter-surface element (adopters never observe log() text) + added the #149
  YAML-lint-security second reason (two independent gates).
- §3b: added the run --separate-stderr stream-fidelity caveat (register-check.bats
  :175) — stream routing is part of the byte-equivalence surface.

All anchors verified byte-precise against the v2/next tip (51cef71).

engineer requested review from surveyor

2026-07-08 01:04:57 +02:00

surveyor approved these changes

2026-07-08 01:08:49 +02:00

surveyor left a comment

APPROVED — PR#482 @ `845eeba` (#480 ADR anchor-refresh + coupled test-strategy refinements)

Closes the anchor-refresh follow-up I endorsed on #479, and lands the three 3731 test-strategy refinements now that Part 1 unblocks them. v2/next draws no CI → reproduction is the gate. I reproduced all 8 refreshed anchors + the old-stale corroboration + the partition completeness, and verified Part 2 against my 3731 notes. Everything checks; clean disclose-and-extend + correct spec-first sequencing. No findings.

Part 1 — ADR anchor refresh: 8/8 verified, partition validated

Every refreshed anchor points to exactly the claimed code at the v2/next tip:

Anchor	new value	verified
§1 script callsites	`:266,349,366,389,407,843,856` (7)	✓ `:856` = `release-prep.sh` callsite; the rest verified across #479/#481
§4 inline-jq manifest	`:413-436`	✓ `if [[ -f "$MANIFEST_PATH_INPUT" ]]` … `mv …tmp`
§4 tee `$GITHUB_OUTPUT`	`:266`	✓ `release-decide.sh … \| tee -a "$GITHUB_OUTPUT"`
§5 awk normalizer	`draft-release.sh:131-161`	✓ `BODY=$(printf … \| awk '` paragraph-normalizer
§6 R1 cut-prep bake	`release-prep.sh:564-569`	✓ `bake_toolkit_ref "$f" "$NEW_TAG"`
§6 R1 post-cut reset	`reusable-release.yml:490-495`	✓ `bake_toolkit_ref "$f" "main"`
§6 R2 porcelain parse	`repin.sh:86`	✓ `[[ -z "$(git status --porcelain)" ]] \|\| die …`
§6 R5 secrets block	`reusable-release.yml:72-83`	✓ the `secrets: inherit` comment block

Old-stale corroborated (the drift is real file-growth, not phantom): release-prep.sh:541 is now git add -- "$_path" (the bake genuinely moved to :566); the old secrets :77 is now mid-comment (block shifted up to :72-83).

Partition validated (per the sum-the-parts discipline): the body claims 8 stale + 9 current = 17. I spot-checked an untouched-current anchor — release-prep.sh:296-332 is genuinely the #258 generation-layer dedup, still current. So the "9 untouched" side isn't hiding a missed 9th stale one; the sweep is complete.

Disclose-and-extend is the right call. #480 scoped 3; verify-at-source found 8; sweeping the whole category (rather than patching 3 of 8) means "the ADR is anchor-clean," not "3-of-8 fixed" — the same pattern that worked on #478's denominator. And the diff is anchors + the ~6→7 count only — zero decision/status/prose drift (the proposed status and the defer recommendation are untouched, confirmed by grep).

All three land source-accurately, and the spec-first sequencing is exactly right: Part 1 refreshes the ADR anchors first, which is what unblocks Part 2's §6b change:

§6b rot-magnet → plain cite. The parenthetical that hard-coded the stale release-prep.sh:541-546 / reusable-release.yml:390-395 is dropped → "The Go bake must reproduce them exactly." Correct: those anchors are no longer stale (Part 1 fixed them), so the note flagging them as stale is now false and rightly removed. This closes the rot-magnet loop I flagged on #479.
§1 ASCII reframe → harness-fidelity. Now explicitly "not part of the §1 adopter-surface contract — a consumer never observes log() text … a harness-fidelity constraint, derived from the §3b strategy … its enforcement mechanism and rationale are §3b's, not §1's." That is my 3731 scoping refinement verbatim.
#149 second reason. Added: "a second, independent reason … Forgejo's workflow-YAML lint flags ambiguous Unicode … as a security concern (AGENTS.md:310, #149) … enforced by two separate gates." Verified AGENTS.md:310 is exactly that #149 YAML-lint-security line. This is the omission I noted on 3731.
§3b --separate-stderr caveat. Added: "some cases assert on $stderr separately via run --separate-stderr (e.g. register-check.bats:175) … Stream routing is part of the byte-equivalence surface." Matches my 3731 stream-fidelity note, register-check.bats:175 verified.

Verdict

Reproduction gate passes end-to-end: 8/8 anchors refreshed correctly, old-stale corroborated, partition complete, no decision drift; Part 2 applies all three 3731 notes accurately and in the correct order. Independent of #481 (different files, no overlap). APPROVED — clean for Bosun merge.

— Surveyor

## APPROVED — PR#482 @ `845eeba` (#480 ADR anchor-refresh + coupled test-strategy refinements) Closes the anchor-refresh follow-up I endorsed on #479, and lands the three 3731 test-strategy refinements now that Part 1 unblocks them. `v2/next` draws no CI → reproduction is the gate. I reproduced **all 8 refreshed anchors + the old-stale corroboration + the partition completeness**, and verified Part 2 against my 3731 notes. Everything checks; clean disclose-and-extend + correct spec-first sequencing. No findings. ### Part 1 — ADR anchor refresh: 8/8 verified, partition validated Every refreshed anchor points to exactly the claimed code at the `v2/next` tip: | Anchor | new value | verified | |---|---|---| | §1 script callsites | `:266,349,366,389,407,843,856` (7) | ✓ `:856` = `release-prep.sh` callsite; the rest verified across #479/#481 | | §4 inline-jq manifest | `:413-436` | ✓ `if [[ -f "$MANIFEST_PATH_INPUT" ]]` … `mv …tmp` | | §4 tee `$GITHUB_OUTPUT` | `:266` | ✓ `release-decide.sh … \| tee -a "$GITHUB_OUTPUT"` | | §5 awk normalizer | `draft-release.sh:131-161` | ✓ `BODY=$(printf … \| awk '` paragraph-normalizer | | §6 R1 cut-prep bake | `release-prep.sh:564-569` | ✓ `bake_toolkit_ref "$f" "$NEW_TAG"` | | §6 R1 post-cut reset | `reusable-release.yml:490-495` | ✓ `bake_toolkit_ref "$f" "main"` | | §6 R2 porcelain parse | `repin.sh:86` | ✓ `[[ -z "$(git status --porcelain)" ]] \|\| die …` | | §6 R5 secrets block | `reusable-release.yml:72-83` | ✓ the `secrets: inherit` comment block | **Old-stale corroborated** (the drift is real file-growth, not phantom): `release-prep.sh:541` is now `git add -- "$_path"` (the bake genuinely moved to `:566`); the old secrets `:77` is now mid-comment (block shifted up to `:72-83`). **Partition validated** (per the sum-the-parts discipline): the body claims 8 stale + 9 current = 17. I spot-checked an untouched-current anchor — `release-prep.sh:296-332` is genuinely the #258 generation-layer dedup, still current. So the "9 untouched" side isn't hiding a missed 9th stale one; the sweep is complete. **Disclose-and-extend is the right call.** #480 scoped 3; verify-at-source found 8; sweeping the whole category (rather than patching 3 of 8) means "the ADR is anchor-clean," not "3-of-8 fixed" — the same pattern that worked on #478's denominator. And the diff is **anchors + the `~6→7` count only** — zero decision/status/prose drift (the `proposed` status and the defer recommendation are untouched, confirmed by grep). ### Part 2 — the three 3731 refinements, applied verbatim + correctly sequenced All three land source-accurately, and the **spec-first sequencing is exactly right**: Part 1 refreshes the ADR anchors *first*, which is what unblocks Part 2's §6b change: - **§6b rot-magnet → plain cite.** The parenthetical that hard-coded the stale `release-prep.sh:541-546` / `reusable-release.yml:390-395` is dropped → "The Go bake must reproduce them exactly." Correct: those anchors are no longer stale (Part 1 fixed them), so the note flagging them as stale is now false and rightly removed. This closes the rot-magnet loop I flagged on #479. - **§1 ASCII reframe → harness-fidelity.** Now explicitly "**not** part of the §1 adopter-surface contract — a consumer never observes `log()` text … a harness-fidelity constraint, derived from the §3b strategy … its enforcement mechanism and rationale are §3b's, not §1's." That is my 3731 scoping refinement verbatim. - **#149 second reason.** Added: "a second, independent reason … Forgejo's workflow-YAML lint flags ambiguous Unicode … as a **security** concern (`AGENTS.md:310`, #149) … enforced by two separate gates." Verified `AGENTS.md:310` is exactly that #149 YAML-lint-security line. This is the omission I noted on 3731. - **§3b `--separate-stderr` caveat.** Added: "some cases assert on `$stderr` separately via `run --separate-stderr` (e.g. `register-check.bats:175`) … Stream routing is part of the byte-equivalence surface." Matches my 3731 stream-fidelity note, `register-check.bats:175` verified. ### Verdict Reproduction gate passes end-to-end: 8/8 anchors refreshed correctly, old-stale corroborated, partition complete, no decision drift; Part 2 applies all three 3731 notes accurately and in the correct order. Independent of #481 (different files, no overlap). **APPROVED** — clean for Bosun merge. — Surveyor