fix(release): stop rejecting the changelog entry pkgmgr itself produced

A heading in the message became a bold line, and markdown-lint reads a bold
line on its own as a heading: MD036. Every structured entry therefore failed
the check it had just been normalised for, and since the loop reopens the
editor on failure there was no text that could end it.

Headings now move below the "## [version]" line the entry is filed under.
A "###" under a "##" is the hierarchy, not a competitor; only "#" and "##"
would have collided, and those are the ones raised.

The findings never reached the person either. They were printed and the
editor took the terminal over in the same breath, so the reason was gone
before it could be read. They are held on screen until Enter, and written
into the editor buffer as ';' lines above the rejected text, where the fix
is actually made; the buffer already drops those lines when it is read back.

transform_changelog_message and lint_changelog_entry were each tested alone,
which is how a transform that produces lint errors went unnoticed. A test now
runs the output of the first through the second.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/pkgmgr/actions/release/files/changelog_lint.py

@@ -7,10 +7,11 @@ import shutil
 import subprocess
 import tempfile
 
-_HEADING = re.compile(r"^\s*#{1,6}\s+(.*?)\s*#*\s*$")
+_HEADING = re.compile(r"^\s*(#{1,6})\s+(.*?)\s*#*\s*$")
 _INLINE_CODE = re.compile(r"`([^`\n]+)`")
 _FINDING = re.compile(r"\bMD\d{3}\b")
 _MULTI_BLANK = re.compile(r"\n{3,}")
+_ENTRY_LEVEL = 3
 
 
 class ChangelogLintError(RuntimeError):
@@ -20,10 +21,10 @@ class ChangelogLintError(RuntimeError):
 def transform_changelog_message(text: str) -> str:
     """Normalise a free-form release message into the changelog house style.
 
-    A leading ``#`` heading becomes a bold line of its own (markdown
-    headings inside an entry body would collide with the ``## [version]``
-    structure), and inline ``code`` spans become ``*italic*`` so the entry
-    stays free of backticks.
+    Headings are pushed below the ``## [version]`` line the entry is filed
+    under, so they nest instead of competing with it. Bolding them instead
+    would read as a heading to markdown-lint and fail MD036. Inline ``code``
+    spans become ``*italic*`` so the entry stays free of backticks.
     """
     text = _INLINE_CODE.sub(r"*\1*", text)
 
@@ -31,9 +32,10 @@ def transform_changelog_message(text: str) -> str:
     for line in text.split("\n"):
         heading = _HEADING.match(line)
         if heading:
+            level = max(len(heading.group(1)), _ENTRY_LEVEL)
             if out and out[-1].strip():
                 out.append("")
-            out.append(f"**{heading.group(1).strip()}**")
+            out.append(f"{'#' * level} {heading.group(2).strip()}")
             out.append("")
         else:
             out.append(line)

src/pkgmgr/actions/release/files/changelog_md.py

@@ -80,6 +80,12 @@ def update_changelog(
             print(f"  - {finding}")
         print()
 
+    def _wait_for_reader() -> None:
+        try:
+            input("[INFO] Press Enter to re-open the editor and fix the entry...")
+        except EOFError:
+            print("[INFO] Re-opening the editor so you can fix the entry...")
+
     if message is not None:
         body, entry = _entry_for(message)
         findings = lint_changelog_entry(changelog_path, entry)
@@ -92,19 +98,21 @@ def update_changelog(
         body, entry = _entry_for(message or f"Release {new_version}")
     else:
         attempt: str | None = None
+        rejected: list[str] | None = None
         while True:
             print(
-                "\n[INFO] Provide the changelog entry — a leading '#' becomes "
-                "bold, `code` becomes italic.\n"
+                "\n[INFO] Provide the changelog entry - a leading '#' becomes "
+                "a sub-heading, `code` becomes italic.\n"
             )
-            raw = _open_editor_for_changelog(attempt)
+            raw = _open_editor_for_changelog(attempt, rejected)
             body, entry = _entry_for(raw or f"Release {new_version}")
             findings = lint_changelog_entry(changelog_path, entry)
             if not findings:
                 break
             _print_findings(findings)
             attempt = body
-            print("[INFO] Re-opening the editor so you can fix the entry...")
+            rejected = findings
+            _wait_for_reader()
 
     changelog = ""
     if os.path.exists(changelog_path):

src/pkgmgr/actions/release/files/editor.py

@@ -6,7 +6,14 @@ import subprocess
 import tempfile
 
 
-def _open_editor_for_changelog(initial_message: str | None = None) -> str:
+def _open_editor_for_changelog(
+    initial_message: str | None = None,
+    findings: list[str] | None = None,
+) -> str:
+    """Args:
+    initial_message: the previous attempt, pre-loaded for editing.
+    findings: why that attempt was rejected, shown above it.
+    """
     editor = os.environ.get("EDITOR", "nano")
 
     with tempfile.NamedTemporaryFile(
@@ -18,9 +25,15 @@ def _open_editor_for_changelog(initial_message: str | None = None) -> str:
         tmp.write(
             "; Write the changelog entry for this release.\n"
             "; Lines starting with ';' are ignored.\n"
-            "; A leading '#' becomes bold; `code` becomes italic.\n"
-            "; Empty result will fall back to a generic message.\n\n"
+            "; A leading '#' becomes a sub-heading; `code` becomes italic.\n"
+            "; Empty result will fall back to a generic message.\n"
         )
+        if findings:
+            tmp.write(";\n; markdown-lint rejected the previous entry:\n")
+            for finding in findings:
+                for line in str(finding).splitlines() or [""]:
+                    tmp.write(f";   {line}\n")
+        tmp.write("\n")
         if initial_message:
             tmp.write(initial_message.strip() + "\n")
         tmp.flush()