chore(release): 0.12.0

.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "bmad-loop",
       "source": "./src/bmad_loop/data/skills",
       "description": "Automation-mode skills driven by the bmad-loop orchestrator: project bootstrap (bmad-loop-setup), interactive escalation resolution (bmad-loop-resolve) and deferred-work sweep triage (bmad-loop-sweep) — the inner dev primitive (which self-reviews and commits) is the upstream bmad-dev-auto skill",
-      "version": "0.11.1",
+      "version": "0.12.0",
       "author": {
         "name": "pinkyd"
       },

CHANGELOG.md

@@ -7,6 +7,8 @@ breaking changes may land in a minor release.
 
 ## [Unreleased]
 
+## [0.12.0] — 2026-09-20
+
 ### Added
 
 - Restore and normalize attempt-owned specs on Windows through NT handle-relative
@@ -478,6 +480,13 @@ breaking changes may land in a minor release.
 
 ### Fixed
 
+- Bound the GitHub release body `scripts/release.py publish` sends at GitHub's
+  125,000-character limit, cutting at an entry boundary and linking the full
+  `CHANGELOG.md` section. An oversize section was rejected with HTTP 422 only after
+  `gh release create` had pushed the tag, stranding a tag with no release that the
+  next publish then treated as already published. `prepare` warns when a section
+  will be truncated.
+
 - Bind legacy migration dispatch and publication to the ledger bytes actually accepted
   (DW-311, DW-316). Retire stale recovery authority when the ledger changes before
   the true post-hook adapter-launch boundary, then publish a validated one-path,
@@ -6114,7 +6123,8 @@ enforced in CI.
   implementation phase, driven by a Python control loop with hook-based session transport and
   resumable on-disk run state.
 
-[Unreleased]: https://github.com/bmad-code-org/bmad-loop/compare/v0.11.1...HEAD
+[Unreleased]: https://github.com/bmad-code-org/bmad-loop/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/bmad-code-org/bmad-loop/releases/tag/v0.12.0
 [0.11.1]: https://github.com/bmad-code-org/bmad-loop/releases/tag/v0.11.1
 [0.11.0]: https://github.com/bmad-code-org/bmad-loop/releases/tag/v0.11.0
 [0.10.0]: https://github.com/bmad-code-org/bmad-loop/releases/tag/v0.10.0

module.yaml

@@ -1,7 +1,7 @@
 code: bmad-loop
 name: BMAD Loop Skills
 description: "Automation-mode skills driven by the bmad-loop orchestrator: interactive escalation resolution (bmad-loop-resolve) and deferred-work sweep triage (bmad-loop-sweep) — the inner dev primitive (which self-reviews and commits) is the upstream bmad-build-auto skill (bmad-dev-auto on pre-rename releases)"
-module_version: 0.11.1
+module_version: 0.12.0
 default_selected: false
 module_greeting: >
   BMAD Loop installed — both the automation skills and the

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bmad-loop"
-version = "0.11.1"
+version = "0.12.0"
 description = "Deterministic ralph-loop orchestrator for the BMAD implementation phase"
 readme = "README.md"
 license = "MIT"

scripts/release.py

@@ -141,6 +141,40 @@ def has_curated_section(text: str, version: str) -> bool:
     return bool(body)
 
 
+# GitHub rejects a release whose body exceeds this many characters with
+# `HTTP 422: body is too long (maximum is 125000 characters)`. `gh release create`
+# creates the tag before the API rejects the body, so an unbounded section leaves a
+# tag with no release behind — and a re-run then sees the tag and refuses to publish.
+GITHUB_NOTES_LIMIT = 125_000
+
+
+def bound_release_notes(notes: str, version: str, url: str, limit: int = GITHUB_NOTES_LIMIT) -> str:
+    """Return ``notes`` if they fit GitHub's release-body limit, else a prefix that
+    does, cut at an entry boundary and closed with a pointer at the full section.
+
+    The CHANGELOG stays the record; the release body is a view of it. Truncating
+    the view is preferable to curating the record down to the limit."""
+    if len(notes) <= limit:
+        return notes
+    footer = (
+        "\n\n---\n\n_Release notes truncated at GitHub's "
+        f"{limit:,}-character limit. The full section is in "
+        f"[CHANGELOG.md]({url}/blob/v{version}/CHANGELOG.md)._"
+    )
+    budget = limit - len(footer)
+    # Cut where the next entry begins so no entry is sliced mid-sentence; fall back
+    # to a hard cut only when the very first entry alone overflows the budget.
+    cut = notes.rfind("\n- ", 0, budget)
+    head = notes[:cut] if cut > 0 else notes[:budget]
+    head = head.rstrip()
+    # A `### Type` heading left with no entries under it points at nothing — drop it.
+    lines = head.splitlines()
+    while lines and lines[-1].startswith("#"):
+        lines.pop()
+    head = "\n".join(lines).rstrip()
+    return head + footer
+
+
 # The shape a promoted heading must take: `## [X.Y.Z] — YYYY-MM-DD`. `section_re`
 # accepts any suffix after `]`, so nothing else notices a dateless or garbled one.
 # Every release heading in CHANGELOG.md matches this — the sole exception is the
@@ -374,7 +408,7 @@ def cmd_prepare(args: argparse.Namespace) -> int:
     changelog = CHANGELOG.read_text()
     problems: list[str] = []
     if branch == "main":
-        problems.append("on `main`; run prepare from a release/feature branch")
+        problems.append("on `main`; run prepare from a feature branch")
     if tag_exists(tag):
         problems.append(f"tag {tag} already exists")
     if not version_gt(version, canonical):
@@ -463,6 +497,21 @@ def cmd_prepare(args: argparse.Namespace) -> int:
 
     print(f"prepare {tag} on branch '{branch}' (was {canonical}, last tag {last_tag or 'none'})")
     print(f"assets: {reason}")
+    if branch.startswith("release/"):
+        # release.yml publishes on push to `release/*` (maintenance branches), so a PR
+        # branch by that name tags its own pre-merge commit the moment it is pushed.
+        print(
+            f"warning: '{branch}' matches release.yml's `release/*` trigger — pushing it "
+            f"publishes {tag} from this branch immediately, before any PR merges. That is "
+            "the maintenance-branch flow; a PR aimed at `main` belongs on `chore/release-X.Y.Z`"
+        )
+    section_len = len(extract_section(changelog, version) or "")
+    if section_len > GITHUB_NOTES_LIMIT:
+        print(
+            f"warning: the `## [{version}]` section is {section_len:,} chars; GitHub caps release "
+            f"notes at {GITHUB_NOTES_LIMIT:,}, so `publish` will truncate the release body and "
+            "link the full CHANGELOG section"
+        )
 
     if args.dry_run:
         print("\n[dry-run] planned actions:")
@@ -523,6 +572,14 @@ def cmd_publish(args: argparse.Namespace) -> int:
     if not notes:
         _die(f"no CHANGELOG `## [{version}]` section — cannot publish release notes")
 
+    bounded = bound_release_notes(notes, version, repo_url())
+    if bounded is not notes:
+        print(
+            f"release notes: CHANGELOG section is {len(notes):,} chars, over GitHub's "
+            f"{GITHUB_NOTES_LIMIT:,} limit — publishing a truncated body that links the full section"
+        )
+    notes = bounded
+
     sha = _git_out("rev-parse", "HEAD")
     if args.dry_run:
         print(f"[dry-run] would create release {tag} at {sha[:12]} with notes:\n")

src/bmad_loop/__init__.py

@@ -8,4 +8,4 @@
 directory under .bmad-loop/runs/.
 """
 
-__version__ = "0.11.1"
+__version__ = "0.12.0"

src/bmad_loop/data/skills/bmad-loop-setup/assets/module.yaml

@@ -1,7 +1,7 @@
 code: bmad-loop
 name: BMAD Loop Skills
 description: "Automation-mode skills driven by the bmad-loop orchestrator: interactive escalation resolution (bmad-loop-resolve) and deferred-work sweep triage (bmad-loop-sweep) — the inner dev primitive (which self-reviews and commits) is the upstream bmad-build-auto skill (bmad-dev-auto on pre-rename releases)"
-module_version: 0.11.1
+module_version: 0.12.0
 default_selected: false
 module_greeting: >
   BMAD Loop installed — both the automation skills and the

tests/test_release.py

@@ -361,17 +361,103 @@ def test_publish_passes_check_false_so_the_swallow_inspects_the_rc(monkeypatch,
     assert seen["check"] is False
 
 
+# --- publish bounds the release body -------------------------------------- #
+# GitHub rejects a body over 125,000 chars with HTTP 422 *after* `gh` has created the
+# tag, which strands a tag with no release (v0.12.0's first publish). The body is a
+# view of the CHANGELOG, so it is the body that yields, at an entry boundary.
+def _long_section(entries: int, *, width: int = 200) -> str:
+    return "### Fixed\n\n" + "\n".join(f"- Entry {i:05d}. " + "x" * width for i in range(entries))
+
+
+def test_bound_release_notes_returns_short_notes_untouched():
+    notes = "### Fixed\n\n- **A thing.** It no longer breaks."
+    assert release.bound_release_notes(notes, "0.5.0", REPO_URL) is notes
+
+
+def test_bound_release_notes_cuts_at_an_entry_boundary_and_links_the_changelog():
+    notes = _long_section(40)
+    out = release.bound_release_notes(notes, "0.5.0", REPO_URL, limit=2_000)
+    assert len(out) <= 2_000
+    body, _, footer = out.partition("\n\n---\n\n")
+    # Every surviving line is a whole entry — none sliced mid-sentence.
+    assert all(line.startswith("- Entry ") and line.endswith("x") for line in body.splitlines()[2:])
+    assert "- Entry 00000." in body
+    assert f"{REPO_URL}/blob/v0.5.0/CHANGELOG.md" in footer
+    assert "truncated at GitHub's 2,000-character limit" in footer
+
+
+def test_bound_release_notes_drops_a_heading_left_with_no_entries():
+    notes = "### Added\n\n- " + "a" * 400 + "\n\n### Fixed\n\n- " + "b" * 400
+    out = release.bound_release_notes(notes, "0.5.0", REPO_URL, limit=700)
+    body = out.partition("\n\n---\n\n")[0]
+    assert "### Added" in body
+    assert "### Fixed" not in body  # its only entry did not fit, so the heading goes too
+
+
+def test_bound_release_notes_hard_cuts_when_even_the_first_entry_overflows():
+    notes = "- " + "z" * 5_000
+    out = release.bound_release_notes(notes, "0.5.0", REPO_URL, limit=600)
+    assert len(out) <= 600
+    assert out.startswith("- zzz")
+
+
+def test_publish_sends_a_bounded_body_and_says_so(monkeypatch, capsys, tmp_path):
+    cl = tmp_path / "CHANGELOG.md"
+    cl.write_text(SAMPLE.replace("- **A thing.** It no longer breaks.", _long_section(1_000)))
+    monkeypatch.setattr(release, "CHANGELOG", cl)
+    monkeypatch.setattr(release.sync_version, "read_canonical", lambda: "0.5.0")
+    monkeypatch.setattr(release, "tag_exists", lambda tag: False)
+    monkeypatch.setattr(release, "repo_url", lambda: REPO_URL)
+    monkeypatch.setattr(release, "_git_out", lambda *a: "deadbeef" * 5)
+    monkeypatch.setattr(release.shutil, "which", lambda name: f"/usr/bin/{name}")
+    seen: dict[str, object] = {}
+
+    def fake_run(*a, **kw):
+        seen.update(kw)
+        return SimpleNamespace(returncode=0, stdout="", stderr="")
+
+    monkeypatch.setattr(release.subprocess, "run", fake_run)
+    rc = release.cmd_publish(SimpleNamespace(dry_run=False))
+    assert rc == 0
+    sent = seen["input"]
+    assert isinstance(sent, str) and len(sent) <= release.GITHUB_NOTES_LIMIT
+    assert f"{REPO_URL}/blob/v0.5.0/CHANGELOG.md" in sent
+    assert "over GitHub's 125,000 limit" in capsys.readouterr().out
+
+
+def test_prepare_warns_on_a_release_star_branch(monkeypatch, capsys, tmp_path):
+    # `_prepare_dry_run` pins the branch to `release/0.5.0`, the shape release.yml publishes
+    # from on push — the warning is what tells a PR author they are about to self-publish.
+    assert _prepare_dry_run(monkeypatch, tmp_path, PROMOTED) == 0
+    out = capsys.readouterr().out
+    assert "matches release.yml's `release/*` trigger" in out
+
+
+def test_prepare_stays_quiet_on_a_chore_branch(monkeypatch, capsys, tmp_path):
+    assert _prepare_dry_run(monkeypatch, tmp_path, PROMOTED, branch="chore/release-0.5.0") == 0
+    assert "release/*" not in capsys.readouterr().out
+
+
+def test_prepare_warns_when_the_section_will_be_truncated(monkeypatch, capsys, tmp_path):
+    long_promoted = PROMOTED.replace("- **A thing.** It no longer breaks.", _long_section(1_000))
+    assert _prepare_dry_run(monkeypatch, tmp_path, long_promoted) == 0
+    out = capsys.readouterr().out
+    assert "warning:" in out and "will truncate the release body" in out
+
+
 # --- prepare refuses an unpromoted changelog -------------------------------- #
 # `--dry-run` still runs every precondition before returning, so it drives the guard
 # without mutating anything; `no_assets` + an absent `trunk` keep the whole path
 # subprocess-free.
-def _prepare_dry_run(monkeypatch, tmp_path, changelog_text, *, version="0.5.0"):
+def _prepare_dry_run(
+    monkeypatch, tmp_path, changelog_text, *, version="0.5.0", branch="release/0.5.0"
+):
     cl = tmp_path / "CHANGELOG.md"
     cl.write_text(changelog_text)
     monkeypatch.setattr(release, "CHANGELOG", cl)
     monkeypatch.setattr(release.sync_version, "read_canonical", lambda: "0.4.3")
     monkeypatch.setattr(release, "repo_url", lambda: REPO_URL)
-    monkeypatch.setattr(release, "current_branch", lambda: "release/0.5.0")
+    monkeypatch.setattr(release, "current_branch", lambda: branch)
     monkeypatch.setattr(release, "last_release_tag", lambda: "v0.4.3")
     monkeypatch.setattr(release, "tag_exists", lambda tag: False)
     monkeypatch.setattr(release, "dirty_paths", lambda: ["CHANGELOG.md"])