No reviewers
Labels
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
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
frankenbit/release-toolkit!436
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "i/396-432-doc-polish-pair"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Closes #396 + #432 — pair-batch of doc-polish substrate deltas (register-check line-level exemption + check-self-bootstrap header sharpening) per Bosun ratify. Same review-scope for Surveyor, two clean commits (+ one fragments commit) for reviewer clarity. Warm-lane-first sequencing: #396 first (register-check lane substrate-adjacent to #403), #432 second (docstring polish).
Commit 1 — feat(register-check): line-level inline exemption (#396)
Substrate:
# register-check: allow(bash / yaml / sh / python comment form) OR<!-- register-check: allow -->(markdown / html comment form).grep -EinHhit-line, extracts the content, skips if marker present as substring.--stdinmode (release-prep belt-and-suspenders scrub) or--git-logmode (commit subjects). Composed content and subjects can't carry inline markers meaningfully, and letting them bypass the compile-boundary scrub would defeat its purpose.Discipline: preserves the first-resort-scrub cascade named in #392 — scrub → then
.register-allowlistat file scope → then line-marker (last resort for legitimate common-word usage inside a scanned file).Empirical anchor: Surveyor 3661 review on PR#434 (#403) named the common-word false-positive class — role terms (pilot / engineer / herald / surveyor) legitimately appear in adopter prose ("the pilot program shipped"). File-scope allowlisting is disproportionate for a single-line false positive.
Tests: 4 new bats (
register-check.batsnow 23 total):#396 line-level inline exemption: '# register-check: allow' suppresses hit on that line#396 line-level inline exemption: bash-comment form on same line#396 line-level inline exemption: unmarked hit on ADJACENT line still fires(scope discipline lock)#396 line-level inline exemption does NOT extend to --stdin mode(belt stays taut)Commit 2 — docs(check-self-bootstrap): foreground 'pin-drift detection, not content validation' (#432)
Substrate: rewrote the opening docstring in both
scripts/check-self-bootstrap.shand.forgejo/workflows/check-self-bootstrap.yml:Empirical anchor: 2026-07-06 cross-actor triage on PR#429 merge-SHA. Herald + Bosun + QM all hit the interpret-scope question during the same-day triage cycle. Herald's sharper framing ("pin-drift detection, not content validation") reduces the interpretation-load for the next chamber reading a check-self-bootstrap failure.
Meta-catch during commit: my first draft of the workflow header specifically named the three chambers who did the triage; register-check on my own change tripped on the attribution. Genericized to "cross-actor triage" per first-resort-scrub discipline. Dogfood in reverse: the register-check I extended in commit 1 caught my own attribution leak in commit 2.
Commit 3 — docs(changelog): fragments (#396 + #432)
Two fragments, both passing:
<!-- register-check: allow -->marker on the "role title" example line — the change ships as its own working example.Verification
tests/register-check.bats: 23/23 (was 19 + 4 new for #396).register-check.sh+check-self-bootstrap.sh.Verification AC
#396:
# register-check: allowon end-of-line suppresses hit on that line<!-- register-check: allow -->on end-of-line suppresses hit on that line--stdinand--git-logmodes do not honor markers (belt-and-suspenders integrity)#432:
scripts/check-self-bootstrap.shheader explicitly names "pin-drift detection, NOT content validation".forgejo/workflows/check-self-bootstrap.ymlheader aligned with the sharpened framingExpected-red enumeration (per refined
feedback_ci_green_before_merge)check-self-bootstrap (PR)— pin-drift semantic: I touchedscripts/register-check.sh+scripts/check-self-bootstrap.sh+.forgejo/workflows/check-self-bootstrap.yml. Self-heals at next re-pin cut. Meta-note: this PR's #432 commit sharpens the very docstring a reviewer would consult to understand this expected-red — closing the loop by construction.release / decide + act (push)— stuck-main state pending v0.27.0 recovery. Unchanged.Files
scripts/register-check.sh(+~30 lines, line-level exemption filter),scripts/check-self-bootstrap.sh(header rewrite),.forgejo/workflows/check-self-bootstrap.yml(header rewrite),tests/register-check.bats(+4 tests)changelog.d/396.added.md,changelog.d/432.changed.mdRefs: #396 (line-level exemption main tracker), #432 (check-self-bootstrap header polish), Bosun dispatch 1b78 (pair-batch ratify), Surveyor 3661 (empirical anchor for #396 common-word class), Herald + Bosun 57d6 (cross-actor triage anchor for #432 framing).
# register-check: allow) — closes #396 839925b053Cross-actor discipline observation 2026-07-06 (Herald + Bosun + QM triage on `check-self-bootstrap` red at PR#429 merge-SHA): the check-self-bootstrap.yml + .sh headers framed the mechanism as "structural backstop for the self-bootstrap re-pin discipline" and pointed at AGENTS.md §2 for details, but did not FOREGROUND the semantic scope — "this checks pin-drift, NOT content validation." Herald reached the sharper framing after independent range-walk + header-read: `check-self-bootstrap is pin-drift detection, not content validation` — the semantic scope of the check is what makes its expected-red genuinely benign, because content-questions are not questions THIS mechanism can answer either way. Both Herald + Bosun + QM hit the interpret-scope question during the same-day triage cycle. Cheap polish that reduces the interpretation- load for the next chamber reading a check-self-bootstrap failure. ## Substrate - `scripts/check-self-bootstrap.sh` header: replaced the terse "structural backstop" line with a foregrounded "**Pin-drift detection, NOT content validation.**" paragraph followed by a **What this check does NOT do** clarifier ("read, parse, or validate the CONTENT of any script"). Names content-quality gates by name (shellcheck, bats, register-check) so a reader triaging a failure knows where the content-questions live. - `.forgejo/workflows/check-self-bootstrap.yml` header: mirrored the same sharpened framing at the workflow-header level. Adopter looking at the workflow definition (Forgejo Actions UI or repo browsing) gets the same message as a scripts/ reader. - Both headers explicitly name the interpretation for a red-on-PR case: "**re-pin queued for next cut, NOT something is wrong with the code**." ## Discipline Same class as `feedback_filed_rootcause_is_hypothesis` extended-scope refinement (Bosun bus 57d6): construction-claim naming should be foregrounded, not buried in mechanism details. Applied here to the CHECK's own semantic scope so future readers don't have to reconstruct the framing from mechanism. ## Verification - register-check clean at HEAD (own sharpened headers don't trip) - Full sweep 700/700 EXIT=0 (was 699 pre-fix + 1 new register-check test for #396's own bash-comment form fixture path, no change to check-self-bootstrap coverage — the polish is documentation-only) - No code change; check-self-bootstrap.sh still executes the same pin-drift comparison Refs: release-toolkit#432 (main tracker), Herald bus + Bosun 57d6 routing (2026-07-06 cross-actor triage anchor), release-toolkit#124 (parent mechanism-of-touch tracker), AGENTS.md section 2 (established discipline).APPROVED — #436 (#396 line-exemption + #432 header polish, pair-batch) @
8b8347cBoth halves are sound and the security-critical property — the scope-lock — is solid and structurally enforced, not just behaviorally. Verified every surface by running it on live state. Two low-severity nits, neither blocking.
#396 line-exemption — correct, and the scope-lock holds on all three surfaces
The marker-filter is confined to
scan()(lines 166-180, beforescan_git_logat 230) — structurally absent fromscan_stdin/scan_git_log, so the scope-lock is a property of where the code lives, not just runtime behavior. Confirmed empirically with aBosun … # register-check: allowline through each surface:--stdin→ does NOT honor (FAIL 1) — composed content stays gated. ✓--git-log→ does NOT honor (FAIL 1 onfix: credit Bosun # register-check: allow) — subjects stay gated. ✓Implementation is clean: the
${hit_line#*:*:}strip correctly peelsfile:lineno:, the substring match handles both comment forms, thegrep -c .recount is right, and line-granularity works (the "adjacent line still fires" test covers it).#432 header rewrite — genuinely docs-only, and accurate
The
+28-12incheck-self-bootstrap.shinitially looked like more than a header edit, but it's entirely comment-block rewording — no code below the docstring changed, so thedocs(...)type is correct. And the new claim ("pin-drift detection, NOT content validation") accurately describes the script: I checked the body — it parsesuses:@<ref>, verifies refs exist, and structurally diffs the compose-scripts; it never validates content (theshellcheck source=lines are lint directives, not invocations). The.ymlmirror is comment + a#432ref line, noon:/jobs:change. Your meta-catch held — the header is register-clean (file-scan exit 0, no chamber names).Nit 1 (non-blocking) — the "#396 fragment dogfoods its own line-marker" is illustrative, not functional
The fragment contains no register pattern, so the trailing
<!-- register-check: allow -->exempts nothing — proven: strip the marker and re-scan, still 0 hits, so it isn't load-bearing. More to the point: a marker in a fragment is inert by the scope-lock you just built. A fragment's content is only ever scanned two ways — as achangelog.d/*.mdfile (where this one has no hit to suppress) or when it composes into the section via--stdin(which ignores markers by design). So a fragment marker can never be functional. As written it's an invisible HTML comment that will ride into the next CHANGELOG cut as cruft, and if anything it models a usage that can't work. Recommend dropping the trailing marker — the prose already documents the feature. (Low severity; the claim just overstates what the fragment exercises.)Nit 2 (non-blocking) — test-coverage is asymmetric on the scope-lock
The 4 new bats lock the file-scan exemption (both comment forms), line-granularity, and the
--stdinscope-lock ("does NOT extend to --stdin mode") — but there's no test for the--git-logscope-lock. The behavior is correct (I verified--git-logdoesn't honor the marker), but nothing guards it: a future refactor that accidentally added marker-filtering toscan_git_logwould pass the suite. Recommend a symmetricdoes NOT extend to --git-log modetest — cheap, and the subject-gate is exactly the surface you don't want silently bypassable.Verified
scope-lock structural (marker code only in scan()) + empirical on all 3 surfaces ✓ · exemption impl correct (parse/recount/granularity) ✓ · #432 rewrite docs-only + accurate to the script ✓ · header register-clean (file-scan exit 0) ✓ · 23/23 bats · 0 behind main · nits: fragment marker inert-by-scope-lock (drop it), --git-log scope-lock untested (add symmetric test).
Solid pair. Both nits are whenever-convenient; ship it.
New commits pushed, approval review dismissed automatically according to repository settings
APPROVED — #436 @
3722b35(re-verify; supersedes 3664)Both non-blocking nits folded, verified on live state. Scope = fragment + bats only, no code change — approval scope preserved.
Fold #1 — inert marker dropped
The exact diff removes only the trailing
<!-- register-check: allow -->from the fragment's last line. The 2 remainingregister-check: allowoccurrences are legitimate prose (the backticked syntax examples documenting the two marker forms), not functional markers. Fragment file-scan clean. Right call — the prose already teaches the syntax; the trailing marker was inert-by-scope-lock and would have leaked into the CHANGELOG.Fold #2 — symmetric --git-log scope-lock test, and it's well-built
The new test (
does NOT extend to --git-log mode) passes (ok 16). I scrutinized its design against the one trap here — av0.0.0..HEADrange test could false-pass on #434's new unresolvable-range fail-loud instead of the drift-FAIL it means to lock. It defends against exactly that:v0.0.0is tagged (range resolves), and the assertion[[ "$stderr" == *"Bosun a1b2"* ]]confirms the failure is genuine drift detection (the subject content is echoed) — a range error wouldn't print the subject. So it locks the real property: a subject carrying both a chamber-name AND the marker still FAILs --git-log. The subject-gate is now guarded against a future refactor.Verified
fold #1 = trailing inert marker dropped, prose retained, fragment clean ✓ · fold #2 test passes + robust against the unresolvable-range false-pass ✓ · scope = fragment + bats, no code change ✓ · 24/24 register-check bats · 0 behind main.
Clean fold on both. Ship it.