feat: enforce publishable changelog entries

actions/changelog-armed/changelog-armed.sh

@@ -134,7 +134,7 @@ EOF
   # the very extractor the publisher uses — changelog_section (#4) — so the
   # guard and the publisher cannot disagree about what a section is or when
   # one counts as empty (rig#67).
-  if [ -z "$(changelog_section "$changelog" "$ver")" ]; then
+  if ! diagnosis="$(changelog_section_problem "$changelog" "$ver")"; then
     cat >&2 <<EOF
 changelog-armed: the version is '$ver' but $changelog has no non-empty
   section for '$ver'. The top section is:
@@ -150,6 +150,8 @@ changelog-armed: the version is '$ver' but $changelog has no non-empty
 
   The fix is the ceremony's first edit: stamp '## Unreleased' into
   '## $ver — DATE', then put an empty '## Unreleased' back above it.
+
+  $diagnosis
 EOF
     exit 1
   fi

bin/changelog-section

@@ -16,9 +16,10 @@ fi
   exit 1
 }
 
-notes="$(changelog_section "$changelog" "$ver")"
-[ -n "$notes" ] || {
+if ! diagnosis="$(changelog_section_problem "$changelog" "$ver")"; then
   echo "changelog-section: $changelog has no section for '$ver' — the release PR stamps the Unreleased section with version + date BEFORE the tag" >&2
+  printf 'changelog-section: %s\n' "$diagnosis" >&2
   exit 1
-}
+fi
+notes="$(changelog_section "$changelog" "$ver")"
 printf '%s\n' "$notes"

test/changelog-armed.test.sh

@@ -53,6 +53,25 @@ tree dev-armed 1.2.4-dev <<'EOF'
 EOF
 check "-dev + Unreleased on top passes" 0 "agrees" in_tree dev-armed
 
+tree dev-seeded 1.2.4-dev <<'EOF'
+# Changelog
+
+## Unreleased
+
+### Added
+
+### Changed
+
+### Fixed
+
+## 1.2.3 — 2026-07-20
+
+### Fixed
+
+- The shipped entry.
+EOF
+check "-dev + seeded empty Unreleased headings passes" 0 "agrees" in_tree dev-seeded
+
 tree dev-stamped 1.2.4-dev <<'EOF'
 # Changelog
 
@@ -90,6 +109,34 @@ tree bare-stamped 1.2.3 <<'EOF'
 EOF
 check "bare + own stamped section on top passes" 0 "agrees" in_tree bare-stamped
 
+tree bare-dangling-heading 1.2.3 <<'EOF'
+# Changelog
+
+## 1.2.3 — 2026-07-20
+
+### Added
+EOF
+check "bare + dangling heading fails with the heading diagnosis" 1 \
+  "section '1.2.3' has no entries — a heading is not an entry" \
+  in_tree bare-dangling-heading
+check "bare + dangling heading keeps the half-ceremony remedy" 1 \
+  "HALF-DONE ceremony" in_tree bare-dangling-heading
+
+tree bare-partly-dangling 1.2.3 <<'EOF'
+# Changelog
+
+## 1.2.3 — 2026-07-20
+
+### Added
+
+### Fixed
+
+- Fixed entry.
+EOF
+check "bare + one empty grouped heading names the first empty heading" 1 \
+  "section '1.2.3' has an empty heading: '### Added'" \
+  in_tree bare-partly-dangling
+
 tree bare-empty-stamp 1.2.3 <<'EOF'
 # Changelog
 

test/changelog.test.sh

@@ -133,6 +133,14 @@ check "wrapper publishes the requested body" 0 "The seven-oh entry" "$WRAPPER" 0
 check "wrapper refuses an empty section" 1 "no section for '0.5.0'" "$WRAPPER" 0.5.0 "$FIXTURE"
 check "wrapper refuses an absent section" 1 "no section for '9.9.9'" "$WRAPPER" 9.9.9 "$FIXTURE"
 check "wrapper explains how the release PR fixes refusal" 1 "stamps the Unreleased section" "$WRAPPER" 9.9.9 "$FIXTURE"
+check "wrapper refuses a heading-only version section" 1 \
+  "section '1.5.0' has no entries — a heading is not an entry" \
+  "$WRAPPER" 1.5.0 "$PROBLEM_FIXTURE"
+check "wrapper names the first dangling heading" 1 \
+  "section '1.6.0' has an empty heading: '### Added'" \
+  "$WRAPPER" 1.6.0 "$PROBLEM_FIXTURE"
+check "wrapper prints seeded empty Unreleased without refusing" 0 "### Added" \
+  "$WRAPPER" Unreleased "$PROBLEM_FIXTURE"
 check "wrapper requires a version" 2 "usage:" "$WRAPPER"
 check "wrapper refuses a missing file" 1 "no such file" "$WRAPPER" 1.0.0 "$TMP/missing.md"