From 388961fd31853acc5c8d11412e200df23d4ce394 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 4 Oct 2026 14:30:31 -0400
Subject: [PATCH 1/3] feat(scripts): add changelog-fragment tooling with no
 plugin opted in

Phase 1 of ADR 0048 (#6006). Adds the fragment tooling and the shared bump
predicate; scripts/fragment-plugins.txt is empty, so every plugin keeps the
per-PR bump and no gate changes its answer.

- scripts/new-changelog-fragment.sh <plugin> <bump> writes
  .changes/<plugin>/<branch-slug>-<8 hex>.md with the front matter.
- scripts/check-changelog-fragments.sh validates fragments (--check),
  requires one for a fragment-mode plugin whose shipped files changed
  (--check-required <base>), and fails a release that leaves a base fragment
  unconsumed for a plugin it bumps (--check-release <base>).
- scripts/release-plugins.sh raises each plugin once at its highest bump,
  writes one CHANGELOG entry merged section by section in fragment commit
  order, sets version in plugin.json only, and deletes consumed fragments;
  all-none plugins lose their fragments without a bump.
- scripts/lib/changelog-fragments.sh holds the shared predicate "version
  moved, or a fragment-mode plugin added a non-none fragment", now used by
  check-vendor-version-bump.sh, sync-shared-copies.sh --check-bump and
  check-standards-contract-bump.sh.

Part of #6006.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 scripts/check-changelog-fragments.sh          | 173 +++++++++++++
 scripts/check-changelog-fragments.test.sh     | 236 ++++++++++++++++++
 scripts/check-script-contract.test.sh         |  13 +
 scripts/check-standards-contract-bump.sh      |  11 +-
 scripts/check-standards-contract-bump.test.sh |  16 ++
 scripts/check-vendor-version-bump.sh          |  18 +-
 scripts/check-vendor-version-bump.test.sh     |  30 +++
 scripts/fragment-plugins.txt                  |   5 +
 scripts/lib/changelog-fragments.sh            | 166 ++++++++++++
 scripts/lib/changelog-fragments.test.sh       | 103 ++++++++
 scripts/lib/gate-entry.sh                     |   4 +-
 scripts/lib/gate-entry.test.sh                |   1 +
 scripts/new-changelog-fragment.sh             |  58 +++++
 scripts/new-changelog-fragment.test.sh        |  90 +++++++
 scripts/release-plugins.sh                    | 192 ++++++++++++++
 scripts/release-plugins.test.sh               | 217 ++++++++++++++++
 scripts/sync-shared-copies.sh                 |  12 +-
 scripts/sync-shared-copies.test.sh            |  19 ++
 18 files changed, 1355 insertions(+), 9 deletions(-)
 create mode 100755 scripts/check-changelog-fragments.sh
 create mode 100755 scripts/check-changelog-fragments.test.sh
 create mode 100644 scripts/fragment-plugins.txt
 create mode 100644 scripts/lib/changelog-fragments.sh
 create mode 100755 scripts/lib/changelog-fragments.test.sh
 create mode 100755 scripts/new-changelog-fragment.sh
 create mode 100755 scripts/new-changelog-fragment.test.sh
 create mode 100755 scripts/release-plugins.sh
 create mode 100755 scripts/release-plugins.test.sh

diff --git a/scripts/check-changelog-fragments.sh b/scripts/check-changelog-fragments.sh
new file mode 100755
index 0000000000..92fae27545
--- /dev/null
+++ b/scripts/check-changelog-fragments.sh
@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# Gates for changelog fragments (ADR 0048).
+#
+#   scripts/check-changelog-fragments.sh --check
+#       every file under .changes/ is a valid fragment: .changes/<plugin>/
+#       <branch-slug>-<8 hex>.md for a plugin in fragment mode, front matter
+#       with one valid `bump`, and a body of known `###` sections (or, for
+#       `bump: none`, a non-empty reason)
+#   scripts/check-changelog-fragments.sh --check-required <base-ref>
+#       a change set that changes a fragment-mode plugin's shipped files adds or
+#       modifies a fragment for it; a fragment it adds must not already exist at
+#       <base-ref>
+#   scripts/check-changelog-fragments.sh --check-release <base-ref>
+#       for the release pull request: <base-ref> holds no fragment this release
+#       left unconsumed for a plugin whose version it bumps
+#
+# Shipped files are everything under plugins/<name>/ except CHANGELOG.md and a
+# plugin.json edit to `version` alone: those two are what a release writes, so
+# the release pull request needs no fragment of its own.
+#
+# The diff modes read the change set as check-changelog-parity.sh does: fork
+# point to branch tip, with a pull_request merge commit resolved to its branch
+# tip.
+#
+# Exit 0 clean, 1 findings, 2 environment or usage; findings on stderr. That is
+# the check-script family contract stated in README.md.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 2
+cd "$SCRIPT_DIR/.." || exit 2
+# shellcheck source=lib/gate-entry.sh
+. "$SCRIPT_DIR/lib/gate-entry.sh" || exit 2
+# shellcheck source=lib/changelog-fragments.sh
+. "$SCRIPT_DIR/lib/changelog-fragments.sh" || exit 2
+
+self="$(basename "$0")"
+GE_FLAGS=("--check" "--check-required:ref" "--check-release:ref")
+GE_BAD_REF_MSG="$self: base ref '${2-}' is not a resolvable commit."
+# shellcheck disable=SC2310  # the non-zero return IS the handled case
+if ! gate_entry::classify "$@"; then
+  echo "usage: $self [--check | --check-required <base-ref> | --check-release <base-ref>]" >&2
+  exit 2
+fi
+mode="$GE_MODE"
+base="$GE_REF"
+
+if [[ "$mode" == --check ]]; then
+  fragments=()
+  if [[ -d .changes ]]; then
+    mapfile -t fragments < <(find .changes -type f | LC_ALL=C sort)
+  fi
+  invalid=0
+  for path in ${fragments[@]+"${fragments[@]}"}; do
+    changelog_fragments::validate "$path"
+    case $? in
+    0) ;;
+    1) invalid=$((invalid + 1)) ;;
+    *) exit 2 ;;
+    esac
+  done
+  if ((invalid > 0)); then
+    echo "$invalid of ${#fragments[@]} changelog fragment(s) are invalid; see docs/adr/0048-release-plugins-from-changelog-fragments-through-a-bot-maintained-release-pr.md for the format." >&2
+    gate_entry::finish 1
+  fi
+  echo "All ${#fragments[@]} changelog fragment(s) under .changes/ are valid."
+  gate_entry::finish 0
+fi
+
+if ! jq --version >/dev/null 2>&1; then
+  echo "$self: jq is required to read manifest versions; refusing to pass without it." >&2
+  exit 2
+fi
+
+head_commit=HEAD
+if git rev-parse -q --verify 'HEAD^2' >/dev/null 2>&1 && git merge-base --is-ancestor 'HEAD^1' "$base" 2>/dev/null; then
+  head_commit='HEAD^2'
+fi
+if ! merge_base="$(git merge-base "$base" "$head_commit")"; then
+  echo "$self: 'git merge-base $base $head_commit' failed; refusing to pass without checking." >&2
+  exit 2
+fi
+status_file="$(mktemp)" || exit 2
+trap 'rm -f "$status_file"' EXIT
+if ! git diff --name-status --no-renames -z "$merge_base" "$head_commit" >"$status_file"; then
+  echo "$self: the diff from $merge_base to $head_commit failed; refusing to pass without checking." >&2
+  exit 2
+fi
+
+manifest_version() { git show "$1:$2" 2>/dev/null | jq -r '.version // empty' 2>/dev/null; }
+manifest_sans_version() { git show "$1:$2" 2>/dev/null | jq -cS 'del(.version)' 2>/dev/null; }
+
+declare -A shipped=() covered=() bumped=() consumed=()
+added_fragments=()
+while IFS= read -r -d '' status && IFS= read -r -d '' path; do
+  case "$path" in
+  .changes/*/*)
+    rest="${path#.changes/}"
+    case "$status" in
+    A)
+      covered["${rest%%/*}"]=1
+      added_fragments+=("$path")
+      ;;
+    M) covered["${rest%%/*}"]=1 ;;
+    D) consumed["$path"]=1 ;;
+    *) ;;
+    esac
+    ;;
+  plugins/*/CHANGELOG.md) ;;
+  plugins/*/.claude-plugin/plugin.json)
+    rest="${path#plugins/}"
+    name="${rest%%/*}"
+    if [[ "$(manifest_version "$merge_base" "$path")" != "$(manifest_version "$head_commit" "$path")" ]]; then
+      bumped["$name"]=1
+    fi
+    if [[ "$(manifest_sans_version "$merge_base" "$path")" != "$(manifest_sans_version "$head_commit" "$path")" ]]; then
+      shipped["$name"]=1
+    fi
+    ;;
+  plugins/*/*)
+    rest="${path#plugins/}"
+    shipped["${rest%%/*}"]=1
+    ;;
+  *) ;;
+  esac
+done <"$status_file"
+
+if [[ "$mode" == --check-required ]]; then
+  findings=0
+  for path in ${added_fragments[@]+"${added_fragments[@]}"}; do
+    if git cat-file -e "$base:$path" 2>/dev/null; then
+      echo "FRAGMENT PATH TAKEN: $path already exists at $base; create a new one with scripts/new-changelog-fragment.sh." >&2
+      findings=$((findings + 1))
+    fi
+  done
+  checked=0
+  for name in "${!shipped[@]}"; do
+    changelog_fragments::in_mode "$name"
+    case $? in
+    0) ;;
+    1) continue ;;
+    *) exit 2 ;;
+    esac
+    checked=$((checked + 1))
+    [[ -z "${covered[$name]:-}" ]] || continue
+    echo "MISSING FRAGMENT: this change set changes files under plugins/$name/ but adds or edits no fragment under .changes/$name/." >&2
+    echo "  Run scripts/new-changelog-fragment.sh $name <major|minor|patch|none> and describe the change; use none, with a reason, when it needs no release." >&2
+    findings=$((findings + 1))
+  done
+  if ((findings > 0)); then
+    gate_entry::finish 1
+  fi
+  echo "Every fragment-mode plugin this change set changes ($checked) has a fragment, and no added fragment path exists at $base."
+  gate_entry::finish 0
+fi
+
+# --check-release
+findings=0
+for name in "${!bumped[@]}"; do
+  if ! pending="$(git ls-tree -r --name-only "$base" -- ".changes/$name/")"; then
+    echo "$self: 'git ls-tree $base -- .changes/$name/' failed; refusing to pass without checking." >&2
+    exit 2
+  fi
+  while IFS= read -r path; do
+    [[ -n "$path" && -z "${consumed[$path]:-}" ]] || continue
+    echo "UNCONSUMED FRAGMENT: $path is on $base but this release bumps $name without it; rebuild the release from $base." >&2
+    findings=$((findings + 1))
+  done <<<"$pending"
+done
+if ((findings > 0)); then
+  gate_entry::finish 1
+fi
+echo "This release leaves no fragment on $base unconsumed for the ${#bumped[@]} plugin(s) it bumps."
+gate_entry::finish 0
diff --git a/scripts/check-changelog-fragments.test.sh b/scripts/check-changelog-fragments.test.sh
new file mode 100755
index 0000000000..88bbb8781a
--- /dev/null
+++ b/scripts/check-changelog-fragments.test.sh
@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# Unit tests for check-changelog-fragments.sh. Each case builds a throwaway git
+# repo holding the gate, scripts/lib/ and a scripts/fragment-plugins.txt, and
+# runs the gate against it.
+set -uo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$SELF_DIR/check-changelog-fragments.sh"
+. "$SELF_DIR/test-git-helpers.sh"
+
+# shellcheck source=lib/test-harness.sh
+. "$SELF_DIR/lib/test-harness.sh"
+# shellcheck source=lib/fixture-tree.sh
+. "$SELF_DIR/lib/fixture-tree.sh"
+
+f=""
+
+# base_fixture <out-var> [listed...] — plugins alpha and beta at 1.0.0, the
+# named ones in fragment mode, committed on main.
+base_fixture() {
+  local dir name
+  fixture_tree::build "$1" --sut "$SCRIPT" --git --plugins --label fragments || return 1
+  dir="${!1}"
+  shift
+  for name in alpha beta; do
+    mkdir -p "$dir/plugins/$name/.claude-plugin" "$dir/plugins/$name/skills"
+    printf '{\n  "name": "%s",\n  "version": "1.0.0"\n}\n' "$name" >"$dir/plugins/$name/.claude-plugin/plugin.json"
+    printf '# Changelog\n\n## [1.0.0] - 2026-10-01\n\n### Added\n\n- First.\n' >"$dir/plugins/$name/CHANGELOG.md"
+    printf 'v1\n' >"$dir/plugins/$name/skills/a.md"
+  done
+  printf '%s\n' '# fragment mode' "$@" >"$dir/scripts/fragment-plugins.txt"
+  git_test_config "$dir" add -A
+  git_test_config "$dir" commit -qm base
+  git_test_config "$dir" branch -q -M main
+}
+
+# fragment <fixture> <plugin> <name> <bump> [body]
+fragment() {
+  local dir="$1" plugin="$2" name="$3" bump="$4" body="${5-### Fixed
+
+- A fix.}"
+  mkdir -p "$dir/.changes/$plugin"
+  printf -- '---\nbump: %s\n---\n\n%s\n' "$bump" "$body" >"$dir/.changes/$plugin/$name.md"
+}
+
+commit() { git_test_config "$1" add -A && git_test_config "$1" commit -qm "$2"; }
+
+run_gate() (
+  cd "$1" && shift && bash scripts/check-changelog-fragments.sh "$@"
+)
+
+# expect <label> <rc> <needle> <fixture> <args...>
+expect() {
+  local label="$1" want="$2" needle="$3" fixture="$4" out rc
+  shift 4
+  out="$(run_gate "$fixture" "$@" 2>&1)"
+  rc=$?
+  if ((rc == want)) && [[ "$out" == *"$needle"* ]]; then
+    ok "$label"
+  else
+    fail "$label: want rc=$want and '$needle', got rc=$rc: $out"
+  fi
+}
+
+# --- --check ------------------------------------------------------------------
+base_fixture f alpha
+expect "--check passes with no .changes/ directory" 0 "All 0 changelog fragment(s)" "$f" --check
+fragment "$f" alpha feat-x-0123abcd minor
+fragment "$f" alpha fix-y-89abcdef none "Test-only change; nothing ships."
+expect "--check passes valid minor and none fragments" 0 "All 2 changelog fragment(s)" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" beta feat-x-0123abcd minor
+expect "--check rejects a fragment for a plugin not in fragment mode" 1 "NOT IN FRAGMENT MODE: .changes/beta/" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" gamma feat-x-0123abcd minor
+expect "--check rejects a fragment for an unknown plugin" 1 "UNKNOWN PLUGIN" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x minor
+expect "--check rejects a name without the 8-hex suffix" 1 "FRAGMENT NAME" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+mkdir -p "$f/.changes"
+printf 'x\n' >"$f/.changes/stray.md"
+expect "--check rejects a file directly under .changes/" 1 "MISPLACED FRAGMENT" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x-0123abcd huge
+expect "--check rejects an unknown bump level" 1 "bump must be major, minor, patch or none" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+mkdir -p "$f/.changes/alpha"
+printf -- '---\nbump: patch\nscope: x\n---\n\n### Fixed\n\n- x\n' >"$f/.changes/alpha/feat-x-0123abcd.md"
+expect "--check rejects a front matter key other than bump" 1 "a key other than bump" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+mkdir -p "$f/.changes/alpha"
+printf '### Fixed\n\n- x\n' >"$f/.changes/alpha/feat-x-0123abcd.md"
+expect "--check rejects a fragment without front matter" 1 "must open with ---" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x-0123abcd patch "### Tweaked
+
+- x"
+expect "--check rejects an unknown section" 1 'unknown section "### Tweaked"' "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x-0123abcd patch "Just prose."
+expect "--check rejects a release fragment with no ### section" 1 "no ### section" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x-0123abcd patch "### Fixed
+
+### Added
+
+- x"
+expect "--check rejects an empty section" 1 'section "### Fixed" is empty' "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x-0123abcd patch "## [9.9.9]
+
+### Fixed
+
+- x"
+expect "--check rejects a ## heading in the body" 1 "would break the CHANGELOG structure" "$f" --check
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x-0123abcd none ""
+expect "--check rejects a none fragment without a reason" 1 "no line saying why" "$f" --check
+rm -rf "$f"
+
+# --- --check-required -----------------------------------------------------------
+base_fixture f alpha
+git_test_config "$f" checkout -qb feat/x
+printf 'v2\n' >"$f/plugins/alpha/skills/a.md"
+commit "$f" change
+expect "--check-required fails a fragment-mode change with no fragment" 1 "MISSING FRAGMENT: this change set changes files under plugins/alpha/" "$f" --check-required main
+fragment "$f" alpha feat-x-0123abcd patch
+commit "$f" fragment
+expect "--check-required passes once a fragment is added" 0 "has a fragment" "$f" --check-required main
+rm -rf "$f"
+
+base_fixture f alpha
+git_test_config "$f" checkout -qb feat/x
+printf 'v2\n' >"$f/plugins/beta/skills/a.md"
+commit "$f" change
+expect "--check-required leaves a plugin not in fragment mode alone" 0 "has a fragment" "$f" --check-required main
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha feat-x-0123abcd patch
+commit "$f" pending
+git_test_config "$f" checkout -qb feat/y
+printf 'v2\n' >"$f/plugins/alpha/skills/a.md"
+fragment "$f" alpha feat-x-0123abcd none "Edited reason."
+commit "$f" edit
+expect "--check-required counts an edited fragment as covering the change" 0 "has a fragment" "$f" --check-required main
+rm -rf "$f"
+
+base_fixture f alpha
+git_test_config "$f" checkout -qb feat/x
+printf '{\n  "name": "alpha",\n  "version": "1.0.1"\n}\n' >"$f/plugins/alpha/.claude-plugin/plugin.json"
+printf '# Changelog\n\n## [1.0.1] - 2026-10-02\n\n### Fixed\n\n- x\n\n## [1.0.0] - 2026-10-01\n\n### Added\n\n- First.\n' >"$f/plugins/alpha/CHANGELOG.md"
+commit "$f" release
+expect "--check-required exempts a version-only manifest edit and CHANGELOG.md (the release shape)" 0 "has a fragment" "$f" --check-required main
+rm -rf "$f"
+
+base_fixture f alpha
+git_test_config "$f" checkout -qb feat/x
+printf '{\n  "name": "alpha",\n  "version": "1.0.0",\n  "description": "new"\n}\n' >"$f/plugins/alpha/.claude-plugin/plugin.json"
+commit "$f" describe
+expect "--check-required treats a manifest edit beyond version as shipped" 1 "MISSING FRAGMENT" "$f" --check-required main
+rm -rf "$f"
+
+base_fixture f alpha
+git_test_config "$f" checkout -qb feat/x
+fragment "$f" alpha feat-x-0123abcd patch
+commit "$f" mine
+git_test_config "$f" checkout -q main
+fragment "$f" alpha feat-x-0123abcd minor
+commit "$f" theirs
+git_test_config "$f" checkout -q feat/x
+expect "--check-required rejects an added fragment whose path exists on the base" 1 "FRAGMENT PATH TAKEN: .changes/alpha/feat-x-0123abcd.md" "$f" --check-required main
+rm -rf "$f"
+
+# --- --check-release ------------------------------------------------------------
+# release_branch <fixture>: main holds alpha's fragment; release/plugins consumes
+# it and bumps alpha.
+release_branch() {
+  fragment "$1" alpha feat-x-0123abcd minor
+  commit "$1" pending
+  git_test_config "$1" checkout -qb release/plugins
+  git_test_config "$1" rm -q .changes/alpha/feat-x-0123abcd.md
+  printf '{\n  "name": "alpha",\n  "version": "1.1.0"\n}\n' >"$1/plugins/alpha/.claude-plugin/plugin.json"
+  commit "$1" release
+}
+
+base_fixture f alpha beta
+release_branch "$f"
+expect "--check-release passes when every fragment for a bumped plugin is consumed" 0 "for the 1 plugin(s) it bumps" "$f" --check-release main
+git_test_config "$f" checkout -q main
+fragment "$f" alpha late-z-fedcba98 patch
+fragment "$f" beta late-z-fedcba98 patch
+commit "$f" late
+git_test_config "$f" checkout -q release/plugins
+expect "--check-release fails on a fragment that landed on the base after the release was cut" 1 "UNCONSUMED FRAGMENT: .changes/alpha/late-z-fedcba98.md" "$f" --check-release main
+out="$(run_gate "$f" --check-release main 2>&1)"
+if [[ "$out" != *".changes/beta/"* ]]; then
+  ok "--check-release ignores a pending fragment for a plugin the release does not bump"
+else
+  fail "--check-release should not name beta: $out"
+fi
+rm -rf "$f"
+
+# --- usage ------------------------------------------------------------------------
+base_fixture f alpha
+expect "no arguments exits 2" 2 "usage" "$f"
+expect "--check-required without a ref exits 2" 2 "usage" "$f" --check-required
+expect "an unresolvable base ref exits 2" 2 "not a resolvable commit" "$f" --check-release no-such-ref
+rm -rf "$f"
+
+test_harness::report
diff --git a/scripts/check-script-contract.test.sh b/scripts/check-script-contract.test.sh
index 3f09d87799..87636c9008 100755
--- a/scripts/check-script-contract.test.sh
+++ b/scripts/check-script-contract.test.sh
@@ -67,6 +67,7 @@ REGISTRY=(
   "check-adr-numbers.sh|-|-|adr_numbers"
   "check-all-skills-verb-contract.sh|-|-|-"
   "check-changed-skills.sh|-|-|-"
+  "check-changelog-fragments.sh|-|--check|changelog_fragments"
   "check-changelog-parity.sh|-|--check|changelog_parity"
   "check-conformance-registry.sh|-|-|-"
   "check-cross-plugin-source-drift.sh|-|-|-"
@@ -397,6 +398,17 @@ recipe::changelog_parity() { # <clean|violation>
   capture run_in "$f" bash scripts/check-changelog-parity.sh --check
 }
 
+recipe::changelog_fragments() { # <clean|violation>
+  local listed=alpha
+  [[ "$1" == violation ]] && listed=""
+  fixture_tree::build f --sut "$SELF_DIR/check-changelog-fragments.sh" --plugins || return 2
+  mkdir -p "$f/plugins/alpha/.claude-plugin" "$f/.changes/alpha"
+  printf '%s\n' '{"name":"alpha","version":"0.1.0"}' >"$f/plugins/alpha/.claude-plugin/plugin.json"
+  printf '%s\n' "$listed" >"$f/scripts/fragment-plugins.txt"
+  printf -- '---\nbump: none\n---\n\nTests only.\n' >"$f/.changes/alpha/feat-x-0123abcd.md"
+  capture run_in "$f" bash scripts/check-changelog-fragments.sh --check
+}
+
 recipe::pipefail_grep_q() { # <clean|violation>
   # shellcheck disable=SC2016  # literal shell source for the fixture; nothing here should expand
   local body='grep -q x <<<"$v"'
@@ -418,6 +430,7 @@ declare -A VIOLATION_NEEDLE=(
   [queue_front_matter]='VIOLATION:'
   [html_assets]='MISSING:'
   [changelog_parity]='MISSING CHANGELOG:'
+  [changelog_fragments]='NOT IN FRAGMENT MODE:'
   [docs_naming]='is not lower-kebab-case'
   [adr_numbers]='0001: docs/adr/0001-first.md, docs/adr/0001-second.md'
   [spoke_plugin_root]='plugins/demo/skills/audit/context/step.md: contains'
diff --git a/scripts/check-standards-contract-bump.sh b/scripts/check-standards-contract-bump.sh
index 2994feea3a..fc3c847166 100755
--- a/scripts/check-standards-contract-bump.sh
+++ b/scripts/check-standards-contract-bump.sh
@@ -4,7 +4,8 @@
 #   scripts/check-standards-contract-bump.sh <base-ref>
 #
 # Fails when the contract or its schema changed vs <base-ref> but
-#   (a) a carrying plugin's manifest version did not move: the plugin version
+#   (a) a carrying plugin's manifest version did not move (or, in fragment
+#       mode, no fragment whose bump is not none was added): the plugin version
 #       is the update cache key, or
 #   (b) the standards-contract frontmatter semver did not move: setup's
 #       migration detection reads it, so without a bump content drifts under a
@@ -22,6 +23,8 @@ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$script_dir/.."
 # shellcheck source=lib/gate-entry.sh
 . "$script_dir/lib/gate-entry.sh" || exit 2
+# shellcheck source=lib/changelog-fragments.sh
+. "$script_dir/lib/changelog-fragments.sh" || exit 2
 
 src="docs/conventions/standards/README.md"
 schema="docs/conventions/standards/standards.schema.json"
@@ -79,7 +82,11 @@ for copy in "${carriers[@]}"; do
   base_version=$(git show "$base:$manifest" 2>/dev/null | jq -r '.version // empty' || true)
   [[ -n "$base_version" ]] || continue
   head_version=$(jq -r '.version // empty' "$manifest")
-  if [[ "$head_version" == "$base_version" ]]; then
+  rc=0
+  # shellcheck disable=SC2310  # the non-zero return IS the answer; rc 2 exits below
+  changelog_fragments::bump_delivered "$base" "${rest%%/*}" "$base_version" "$head_version" || rc=$?
+  ((rc < 2)) || exit 2
+  if ((rc == 1)); then
     echo "STALE VERSION: $src changed vs $base but $manifest is still $head_version" >&2
     stale=1
   fi
diff --git a/scripts/check-standards-contract-bump.test.sh b/scripts/check-standards-contract-bump.test.sh
index e6a3ba4a9f..636b10d6e4 100755
--- a/scripts/check-standards-contract-bump.test.sh
+++ b/scripts/check-standards-contract-bump.test.sh
@@ -138,6 +138,22 @@ if out="$(run_gate "$f" "$base" 2>&1)"; then
 else
   fail "the gate should pass when frontmatter, changelog, and manifests all moved, got: $out"
 fi
+
+# --- a fragment stands in for a carrier's bump only in fragment mode ----------
+printf 'planning\n' >"$f/scripts/fragment-plugins.txt"
+bump "$f" planning 0.1.0
+bump "$f" review 0.1.0
+for plugin in planning review; do
+  mkdir -p "$f/.changes/$plugin"
+  printf -- '---\nbump: patch\n---\n\n### Changed\n\n- Contract synced.\n' >"$f/.changes/$plugin/sync-0123abcd.md"
+done
+git -C "$f" add .changes
+out="$(run_gate "$f" "$base" 2>&1)"
+if [[ $? -eq 1 && "$out" == *"plugins/review/.claude-plugin/plugin.json is still 0.1.0"* && "$out" != *plugins/planning/* ]]; then
+  ok "the gate accepts a fragment-mode carrier's fragment and still requires the legacy carrier's bump"
+else
+  fail "expected only review reported stale, got: $out"
+fi
 rm -rf "$f"
 
 # --- carrying plugin manifest not bumped → fail -------------------------------
diff --git a/scripts/check-vendor-version-bump.sh b/scripts/check-vendor-version-bump.sh
index 8fa65304ce..d6a5345593 100755
--- a/scripts/check-vendor-version-bump.sh
+++ b/scripts/check-vendor-version-bump.sh
@@ -17,7 +17,9 @@
 # WHAT IS CHECKED. For every plugin whose tracked plugins/<name>/vendor/ tree
 # differs from <base-ref> — an edit, an addition, or a deletion, since each is
 # a source change installed consumers must receive — the plugin's
-# .claude-plugin/plugin.json `version` must also differ from <base-ref>.
+# .claude-plugin/plugin.json `version` must also differ from <base-ref>, or, for
+# a plugin in fragment mode, the change set must add a changelog fragment whose
+# bump is not none (the shared predicate in scripts/lib/changelog-fragments.sh).
 # General over plugins/*/vendor/ by construction, not a per-plugin list: a
 # future plugin adopting the ADR's intra-plugin shape is covered the moment its
 # vendor/ directory lands. A plugin absent at the base ref is new in this
@@ -40,6 +42,8 @@ self="$(basename "$0")"
 . "$SCRIPT_DIR/lib/changed-files.sh" || exit 2
 # shellcheck source=lib/gate-entry.sh
 . "$SCRIPT_DIR/lib/gate-entry.sh" || exit 2
+# shellcheck source=lib/changelog-fragments.sh
+. "$SCRIPT_DIR/lib/changelog-fragments.sh" || exit 2
 
 # jq is how every manifest version is read below; without it the per-plugin
 # reads all come back empty, which the loop would misread as "new plugin,
@@ -159,10 +163,18 @@ for plugin in "${changed_plugins[@]}"; do
   head_version=$(jq -r '.version // empty' "$manifest" 2>/dev/null || true)
   # A manifest gone (or versionless) at head while vendor/ files still changed
   # is not a bump either; fail rather than skip, so deleting the manifest can
-  # never double as this gate's off switch.
-  if [[ "$head_version" == "$base_version" || -z "$head_version" ]]; then
+  # never double as this gate's off switch. A fragment-mode plugin may carry the
+  # bump as a changelog fragment instead (the shared predicate's other branch).
+  rc=1
+  if [[ -n "$head_version" ]]; then
+    rc=0
+    changelog_fragments::bump_delivered "$base" "$plugin" "$base_version" "$head_version" || rc=$?
+  fi
+  if ((rc == 1)); then
     echo "STALE VERSION: plugins/$plugin/vendor/ changed vs $base but $manifest is still ${head_version:-absent}" >&2
     stale=1
+  elif ((rc != 0)); then
+    exit 2
   fi
 done
 
diff --git a/scripts/check-vendor-version-bump.test.sh b/scripts/check-vendor-version-bump.test.sh
index c6a06edeb2..f59c38f76a 100755
--- a/scripts/check-vendor-version-bump.test.sh
+++ b/scripts/check-vendor-version-bump.test.sh
@@ -163,6 +163,36 @@ else
 fi
 rm -rf "$f"
 
+# --- a fragment carries the bump only in fragment mode -----------------------
+# add_fragment <fixture> <plugin> <bump>: an added changelog fragment.
+add_fragment() {
+  mkdir -p "$1/.changes/$2"
+  printf -- '---\nbump: %s\n---\n\n### Fixed\n\n- x\n' "$3" >"$1/.changes/$2/feat-x-0123abcd.md"
+  git -C "$1" add -A
+}
+base_fixture f
+echo 'module.exports = 2;' >"$f/plugins/alpha/vendor/pkg/index.js"
+printf 'alpha\n' >"$f/scripts/fragment-plugins.txt"
+add_fragment "$f" alpha patch
+if out="$(run_gate "$f" --check-bump HEAD 2>&1)"; then
+  ok "a fragment-mode plugin's vendor change passes with an added patch fragment"
+else
+  fail "a patch fragment should stand in for the bump in fragment mode, got: $out"
+fi
+rm -rf "$f"
+
+base_fixture f
+echo 'module.exports = 2;' >"$f/plugins/alpha/vendor/pkg/index.js"
+add_fragment "$f" alpha patch
+if out="$(run_gate "$f" --check-bump HEAD 2>&1)"; then
+  fail "a fragment must not stand in for a legacy plugin's bump, got success: $out"
+elif grep -q "STALE VERSION: plugins/alpha/vendor/" <<<"$out"; then
+  ok "a plugin not in fragment mode still needs the version bump"
+else
+  fail "expected STALE VERSION for legacy alpha, got: $out"
+fi
+rm -rf "$f"
+
 # --- a plugin new in this change set is exempt ------------------------------
 base_fixture f
 plugin "$f" gamma 0.1.0
diff --git a/scripts/fragment-plugins.txt b/scripts/fragment-plugins.txt
new file mode 100644
index 0000000000..8921f03029
--- /dev/null
+++ b/scripts/fragment-plugins.txt
@@ -0,0 +1,5 @@
+# Plugins in changelog-fragment mode (ADR 0048), one name per line; `#` starts
+# a comment. A listed plugin's pull requests add a fragment under
+# .changes/<plugin>/ (scripts/new-changelog-fragment.sh) instead of bumping
+# plugin.json and CHANGELOG.md, and scripts/release-plugins.sh releases it.
+# Read by scripts/lib/changelog-fragments.sh.
diff --git a/scripts/lib/changelog-fragments.sh b/scripts/lib/changelog-fragments.sh
new file mode 100644
index 0000000000..87d4e8fcc7
--- /dev/null
+++ b/scripts/lib/changelog-fragments.sh
@@ -0,0 +1,166 @@
+# shellcheck shell=bash
+# Changelog fragments (ADR 0048). Sourced, never executed; every caller runs
+# from the repository root.
+#
+# A fragment is .changes/<plugin>/<branch-slug>-<8 hex>.md: YAML front matter
+# carrying one key, `bump: major|minor|patch|none`, then a Keep a Changelog body
+# of `### <Section>` blocks. A `bump: none` fragment needs only a non-empty
+# reason line. scripts/release-plugins.sh turns pending fragments into a version
+# bump and one CHANGELOG entry per plugin.
+#
+# Only plugins named in scripts/fragment-plugins.txt are in fragment mode. A
+# missing list is an empty one: every plugin then keeps the per-PR bump, which is
+# the stricter of the two paths.
+#
+#   changelog_fragments::in_mode <plugin>         0 when <plugin> is listed
+#   changelog_fragments::bump_of <file>           print the fragment's bump; 1 and
+#                                                 a reason on stdout when the front
+#                                                 matter is malformed
+#   changelog_fragments::validate <path>          print each finding on stderr; 1
+#                                                 when there is one
+#   changelog_fragments::bump_delivered <base> <plugin> <base-version> <head-version>
+#                                                 the shared bump predicate: 0 when
+#                                                 the version moved, or the plugin is
+#                                                 listed and the diff against <base>
+#                                                 adds a fragment for it whose bump
+#                                                 is not none; 1 otherwise; 2 when
+#                                                 git fails
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+  printf 'scripts/lib/changelog-fragments.sh is sourced-only\n' >&2
+  exit 2
+fi
+
+if ! declare -F read_list::into >/dev/null 2>&1; then
+  # shellcheck source=read-list.sh
+  . "${BASH_SOURCE[0]%/*}/read-list.sh"
+fi
+
+CF_LIST="scripts/fragment-plugins.txt"
+CF_SECTIONS="Added Changed Deprecated Removed Fixed Security"
+
+declare -gA _CF_MODE=()
+_CF_MODE_LOADED=""
+
+changelog_fragments::in_mode() {
+  local _cf_names=() _cf_name
+  if [[ -z "$_CF_MODE_LOADED" ]]; then
+    _CF_MODE_LOADED=1
+    if [[ -f "$CF_LIST" ]]; then
+      read_list::into _cf_names "$CF_LIST" --comments inline || return 2
+      for _cf_name in ${_cf_names[@]+"${_cf_names[@]}"}; do
+        _CF_MODE["$_cf_name"]=1
+      done
+    fi
+  fi
+  [[ -n "${_CF_MODE[$1]:-}" ]]
+}
+
+changelog_fragments::bump_of() {
+  awk '
+    { sub(/\r$/, "") }
+    NR == 1 { if ($0 != "---") { err = "front matter must open with --- on line 1"; exit } next }
+    $0 == "---" { closed = 1; exit }
+    /^[ \t]*$/ { next }
+    /^bump:/ {
+      if (bump != "") { err = "front matter sets bump twice"; exit }
+      bump = $0; sub(/^bump:[ \t]*/, "", bump); sub(/[ \t]+$/, "", bump)
+      next
+    }
+    { err = "front matter has a key other than bump: " $0; exit }
+    END {
+      if (err == "" && NR == 0) err = "file is empty"
+      if (err == "" && !closed) err = "front matter is not closed with ---"
+      if (err == "" && bump !~ /^(major|minor|patch|none)$/) err = "bump must be major, minor, patch or none, not \"" bump "\""
+      if (err != "") { print err; exit 1 }
+      print bump
+    }
+  ' "$1"
+}
+
+# The lines after the closing front matter delimiter.
+changelog_fragments::body() {
+  awk '{ sub(/\r$/, "") } fm == 2 { print; next } $0 == "---" { fm++ }' "$1"
+}
+
+changelog_fragments::validate() {
+  local path="$1" plugin rest bump problems line
+  rest="${path#.changes/}"
+  plugin="${rest%%/*}"
+  if [[ "$path" != .changes/* || "$rest" != "$plugin/"* || "${rest#*/}" == */* ]]; then
+    echo "MISPLACED FRAGMENT: $path is not .changes/<plugin>/<name>.md." >&2
+    return 1
+  fi
+  if [[ ! "${rest#*/}" =~ ^[a-z0-9][a-z0-9._-]*-[0-9a-f]{8}\.md$ ]]; then
+    echo "FRAGMENT NAME: $path is not named <branch-slug>-<8 hex>.md; create fragments with scripts/new-changelog-fragment.sh." >&2
+    return 1
+  fi
+  if [[ ! -f "plugins/$plugin/.claude-plugin/plugin.json" ]]; then
+    echo "UNKNOWN PLUGIN: $path names '$plugin', which has no plugins/$plugin/.claude-plugin/plugin.json." >&2
+    return 1
+  fi
+  changelog_fragments::in_mode "$plugin"
+  case $? in
+  0) ;;
+  1)
+    echo "NOT IN FRAGMENT MODE: $path is for '$plugin', which $CF_LIST does not list; bump its plugin.json and CHANGELOG.md in the pull request instead." >&2
+    return 1
+    ;;
+  *) return 2 ;;
+  esac
+  if ! bump="$(changelog_fragments::bump_of "$path")"; then
+    echo "FRAGMENT FRONT MATTER: $path: $bump." >&2
+    return 1
+  fi
+  if [[ "$bump" == none ]]; then
+    if ! grep -q '[^[:space:]]' < <(changelog_fragments::body "$path"); then
+      echo "FRAGMENT BODY: $path has bump: none and no line saying why no release is needed." >&2
+      return 1
+    fi
+    return 0
+  fi
+  problems="$(changelog_fragments::body "$path" | awk -v known="$CF_SECTIONS" '
+    BEGIN { n = split(known, k, " "); for (i = 1; i <= n; i++) ok[k[i]] = 1 }
+    /^###[ \t]/ {
+      cur = $0; sub(/^###[ \t]+/, "", cur); sub(/[ \t]+$/, "", cur)
+      if (!(cur in ok)) print "unknown section \"### " cur "\" (use " known ")"
+      if (!(cur in seen)) order[++sections] = cur
+      seen[cur] = 1
+      next
+    }
+    /^##?[ \t]/ { print "a # or ## heading would break the CHANGELOG structure: " $0; next }
+    /[^ \t]/ { if (cur == "") print "text before the first ### section: " $0; else filled[cur] = 1 }
+    END {
+      if (sections == 0) print "no ### section"
+      for (i = 1; i <= sections; i++) if (!(order[i] in filled)) print "section \"### " order[i] "\" is empty"
+    }
+  ')"
+  if [[ -n "$problems" ]]; then
+    while IFS= read -r line; do
+      echo "FRAGMENT BODY: $path: $line." >&2
+    done <<<"$problems"
+    return 1
+  fi
+  return 0
+}
+
+changelog_fragments::bump_delivered() {
+  local base="$1" plugin="$2" base_version="$3" head_version="$4" added path rc
+  if [[ "$head_version" != "$base_version" ]]; then
+    return 0
+  fi
+  changelog_fragments::in_mode "$plugin"
+  rc=$?
+  ((rc == 0)) || return "$rc"
+  if ! added="$(git diff --name-only --no-renames --diff-filter=A "$base" -- ".changes/$plugin/")"; then
+    echo "changelog-fragments: git diff against $base failed for .changes/$plugin/" >&2
+    return 2
+  fi
+  while IFS= read -r path; do
+    [[ -n "$path" && -f "$path" ]] || continue
+    if [[ "$(changelog_fragments::bump_of "$path" 2>/dev/null)" =~ ^(major|minor|patch)$ ]]; then
+      return 0
+    fi
+  done <<<"$added"
+  return 1
+}
diff --git a/scripts/lib/changelog-fragments.test.sh b/scripts/lib/changelog-fragments.test.sh
new file mode 100755
index 0000000000..7dc7944a6f
--- /dev/null
+++ b/scripts/lib/changelog-fragments.test.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# Unit tests for scripts/lib/changelog-fragments.sh: the opt-in list reader and
+# the shared bump predicate. Fragment validation is exercised through
+# scripts/check-changelog-fragments.test.sh.
+#
+# The predicate's contract with its callers (check-vendor-version-bump.sh,
+# sync-shared-copies.sh, check-standards-contract-bump.sh) is that a plugin not
+# in fragment mode answers exactly as "did the manifest version move", so a
+# fragment can never stand in for a legacy plugin's bump.
+set -uo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+LIB="$SELF_DIR/changelog-fragments.sh"
+. "$SELF_DIR/../test-git-helpers.sh"
+
+# shellcheck source=test-harness.sh
+. "$SELF_DIR/test-harness.sh"
+# shellcheck source=fixture-tree.sh
+. "$SELF_DIR/fixture-tree.sh"
+
+f=""
+
+use_lib() {
+  # shellcheck source=changelog-fragments.sh
+  . "$LIB"
+}
+
+# base_fixture <out-var> <list content>: plugins alpha and beta, committed.
+base_fixture() {
+  local dir name
+  fixture_tree::build "$1" --git --plugins --label fragments-lib || return 1
+  dir="${!1}"
+  for name in alpha beta; do
+    mkdir -p "$dir/plugins/$name/.claude-plugin"
+    printf '{"name":"%s","version":"1.0.0"}\n' "$name" >"$dir/plugins/$name/.claude-plugin/plugin.json"
+  done
+  if [[ -n "$2" ]]; then
+    printf '%s\n' "$2" >"$dir/scripts/fragment-plugins.txt"
+  fi
+  git_test_config "$dir" add -A
+  git_test_config "$dir" commit -qm base
+}
+
+fragment() { # <fixture> <plugin> <bump>
+  mkdir -p "$1/.changes/$2"
+  printf -- '---\nbump: %s\n---\n\n### Fixed\n\n- x\n' "$3" >"$1/.changes/$2/feat-x-0123abcd.md"
+  git_test_config "$1" add -A
+}
+
+# delivered <fixture> <plugin> <base-version> <head-version> → the predicate's rc
+delivered() {
+  (cd "$1" && use_lib && changelog_fragments::bump_delivered HEAD "$2" "$3" "$4")
+}
+
+expect_rc() { # <label> <want> <got>
+  if (($2 == $3)); then ok "$1"; else fail "$1: want rc $2, got $3"; fi
+}
+
+# --- in_mode ------------------------------------------------------------------------
+base_fixture f $'# comment\nalpha  # pilot'
+(cd "$f" && use_lib && changelog_fragments::in_mode alpha)
+expect_rc "a listed plugin is in fragment mode, inline comment stripped" 0 $?
+(cd "$f" && use_lib && changelog_fragments::in_mode beta)
+expect_rc "an unlisted plugin is not" 1 $?
+rm -rf "$f"
+
+base_fixture f ""
+(cd "$f" && use_lib && changelog_fragments::in_mode alpha)
+expect_rc "a missing list puts no plugin in fragment mode" 1 $?
+rm -rf "$f"
+
+# --- bump_delivered ---------------------------------------------------------------
+base_fixture f alpha
+delivered "$f" beta 1.0.0 1.0.1
+expect_rc "a moved version is a bump for a legacy plugin" 0 $?
+delivered "$f" alpha 1.0.0 1.0.1
+expect_rc "a moved version is a bump for a fragment-mode plugin" 0 $?
+delivered "$f" alpha 1.0.0 1.0.0
+expect_rc "an unmoved version with no fragment is no bump" 1 $?
+fragment "$f" alpha minor
+delivered "$f" alpha 1.0.0 1.0.0
+expect_rc "an added minor fragment is a bump for a fragment-mode plugin" 0 $?
+fragment "$f" beta minor
+delivered "$f" beta 1.0.0 1.0.0
+expect_rc "an added fragment is no bump for a plugin not in fragment mode" 1 $?
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha none
+delivered "$f" alpha 1.0.0 1.0.0
+expect_rc "an added bump: none fragment is no bump" 1 $?
+rm -rf "$f"
+
+base_fixture f alpha
+fragment "$f" alpha patch
+git_test_config "$f" commit -qm pending
+delivered "$f" alpha 1.0.0 1.0.0
+expect_rc "a fragment already on the base is not this change set's bump" 1 $?
+(cd "$f" && use_lib && changelog_fragments::bump_delivered no-such-ref alpha 1.0.0 1.0.0 2>/dev/null)
+expect_rc "a git failure is rc 2, never a pass or a plain stale" 2 $?
+rm -rf "$f"
+
+test_harness::report
diff --git a/scripts/lib/gate-entry.sh b/scripts/lib/gate-entry.sh
index bb96faef22..6ffd5686b2 100644
--- a/scripts/lib/gate-entry.sh
+++ b/scripts/lib/gate-entry.sh
@@ -16,8 +16,8 @@
 #
 # Adoption: classify and finish are used by check-shell-portability,
 # check-skill-portability, check-skill-precompute-compose, check-changed-skills,
-# check-stale-base-overlap, check-vendor-version-bump, and
-# check-changelog-parity. check-guardrails-ps-differential uses only
+# check-stale-base-overlap, check-vendor-version-bump, check-changelog-parity,
+# and check-changelog-fragments. check-guardrails-ps-differential uses only
 # require_base. Three gates stay outside:
 #   check-docs-only                exits 0 on every fail-closed path, an
 #                                  unresolvable ref included, so the full suite runs
diff --git a/scripts/lib/gate-entry.test.sh b/scripts/lib/gate-entry.test.sh
index 28643a0225..f01e43025f 100755
--- a/scripts/lib/gate-entry.test.sh
+++ b/scripts/lib/gate-entry.test.sh
@@ -289,6 +289,7 @@ BASE_REF_ALLOW=(
   'check-silent-revert.sh|git rev-parse --verify "${commit}:${file}"|captures a blob id'
   'check-stale-base-overlap.sh|base_tip="$(git rev-parse "${base_ref}^{commit}")"|captures the resolved sha'
   "check-changelog-parity.sh|git rev-parse -q --verify 'HEAD^2'|probes for a merge commit, not a base ref"
+  "check-changelog-fragments.sh|git rev-parse -q --verify 'HEAD^2'|probes for a merge commit, not a base ref"
   "dependabot-plugin-bump.sh|git rev-parse -q --verify 'HEAD^2'|probes for a merge commit, not a base ref"
 )
 
diff --git a/scripts/new-changelog-fragment.sh b/scripts/new-changelog-fragment.sh
new file mode 100755
index 0000000000..67a388a443
--- /dev/null
+++ b/scripts/new-changelog-fragment.sh
@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Create a changelog fragment for a plugin in fragment mode (ADR 0048).
+#
+#   scripts/new-changelog-fragment.sh <plugin> <major|minor|patch|none>
+#
+# Writes .changes/<plugin>/<branch-slug>-<8 hex>.md holding the front matter and
+# prints its path. <branch-slug> is the current branch, lowercased, with `/` and
+# any other character outside [a-z0-9._-] replaced by `-`;
+# the random suffix keeps two branches with one slug apart, so no pull request
+# number is needed in advance. Fill in the body afterwards: `### <Section>`
+# blocks (Added, Changed, Deprecated, Removed, Fixed, Security), or for `none`
+# one line saying why no release is needed. scripts/check-changelog-fragments.sh
+# validates it.
+#
+# Exit: 0 written, 2 usage, a plugin that is not in fragment mode, or no branch.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 2
+cd "$SCRIPT_DIR/.." || exit 2
+# shellcheck source=lib/changelog-fragments.sh
+. "$SCRIPT_DIR/lib/changelog-fragments.sh" || exit 2
+
+self="$(basename "$0")"
+if (($# != 2)) || [[ ! "$2" =~ ^(major|minor|patch|none)$ ]]; then
+  echo "usage: $self <plugin> <major|minor|patch|none>" >&2
+  exit 2
+fi
+plugin="$1"
+bump="$2"
+
+if [[ ! -f "plugins/$plugin/.claude-plugin/plugin.json" ]]; then
+  echo "$self: no plugin named '$plugin' (plugins/$plugin/.claude-plugin/plugin.json is missing)." >&2
+  exit 2
+fi
+# shellcheck disable=SC2310  # the non-zero return IS the handled case
+if ! changelog_fragments::in_mode "$plugin"; then
+  echo "$self: '$plugin' is not in fragment mode ($CF_LIST does not list it); bump its plugin.json and CHANGELOG.md in the pull request instead." >&2
+  exit 2
+fi
+if ! branch="$(git symbolic-ref --quiet --short HEAD)"; then
+  echo "$self: HEAD is not on a branch; the fragment name starts with the branch name." >&2
+  exit 2
+fi
+if ! suffix="$(od -An -N4 -tx1 /dev/urandom | tr -d ' \n')" || [[ ! "$suffix" =~ ^[0-9a-f]{8}$ ]]; then
+  echo "$self: could not read 4 random bytes from /dev/urandom." >&2
+  exit 2
+fi
+
+slug="${branch,,}"
+slug="${slug//[^a-z0-9._-]/-}"
+path=".changes/$plugin/$slug-$suffix.md"
+if [[ -e "$path" ]]; then
+  echo "$self: $path already exists; run it again for a new suffix." >&2
+  exit 2
+fi
+mkdir -p ".changes/$plugin" || exit 2
+printf -- '---\nbump: %s\n---\n\n' "$bump" >"$path" || exit 2
+echo "$path"
diff --git a/scripts/new-changelog-fragment.test.sh b/scripts/new-changelog-fragment.test.sh
new file mode 100755
index 0000000000..b82114afd9
--- /dev/null
+++ b/scripts/new-changelog-fragment.test.sh
@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Unit tests for new-changelog-fragment.sh: the name it gives a fragment, the
+# front matter it writes, and the cases it refuses. The fragment it writes is
+# filled in the way a contributor would and run through the shared validator.
+set -uo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$SELF_DIR/new-changelog-fragment.sh"
+. "$SELF_DIR/test-git-helpers.sh"
+
+# shellcheck source=lib/test-harness.sh
+. "$SELF_DIR/lib/test-harness.sh"
+# shellcheck source=lib/fixture-tree.sh
+. "$SELF_DIR/lib/fixture-tree.sh"
+
+f=""
+
+base_fixture() {
+  local dir
+  fixture_tree::build "$1" --sut "$SCRIPT" --git --plugins --label new-fragment || return 1
+  dir="${!1}"
+  mkdir -p "$dir/plugins/alpha/.claude-plugin" "$dir/plugins/beta/.claude-plugin"
+  printf '{"name":"alpha","version":"1.0.0"}\n' >"$dir/plugins/alpha/.claude-plugin/plugin.json"
+  printf '{"name":"beta","version":"1.0.0"}\n' >"$dir/plugins/beta/.claude-plugin/plugin.json"
+  printf 'alpha # pilot\n' >"$dir/scripts/fragment-plugins.txt"
+  git_test_config "$dir" add -A
+  git_test_config "$dir" commit -qm base
+  git_test_config "$dir" checkout -qb Feat/Some_Thing
+}
+
+run_new() (
+  cd "$1" && shift && bash scripts/new-changelog-fragment.sh "$@"
+)
+
+base_fixture f
+first="$(run_new "$f" alpha minor)"
+rc=$?
+second="$(run_new "$f" alpha minor)"
+if ((rc == 0)) && [[ "$first" =~ ^\.changes/alpha/feat-some_thing-[0-9a-f]{8}\.md$ ]]; then
+  ok "names the fragment after the branch slug plus 8 hex characters"
+else
+  fail "unexpected path (rc=$rc): $first"
+fi
+if [[ "$first" != "$second" && -f "$f/$first" && -f "$f/$second" ]]; then
+  ok "two fragments from one branch get different names"
+else
+  fail "expected two distinct files, got '$first' and '$second'"
+fi
+if [[ "$(cat "$f/$first")" == $'---\nbump: minor\n---' ]]; then
+  ok "writes the front matter with the requested bump"
+else
+  fail "unexpected content: $(cat "$f/$first")"
+fi
+printf '### Added\n\n- New thing.\n' >>"$f/$first"
+if (cd "$f" && . scripts/lib/changelog-fragments.sh && changelog_fragments::validate "$first"); then
+  ok "a created fragment, once filled in, passes validation"
+else
+  fail "the filled-in fragment failed validation"
+fi
+rm -rf "$f"
+
+base_fixture f
+out="$(run_new "$f" beta patch 2>&1)"
+if [[ $? -eq 2 && "$out" == *"not in fragment mode"* && ! -e "$f/.changes" ]]; then
+  ok "refuses a plugin that is not in fragment mode"
+else
+  fail "expected exit 2 for beta, got: $out"
+fi
+out="$(run_new "$f" gamma patch 2>&1)"
+if [[ $? -eq 2 && "$out" == *"no plugin named 'gamma'"* ]]; then
+  ok "refuses an unknown plugin"
+else
+  fail "expected exit 2 for gamma, got: $out"
+fi
+out="$(run_new "$f" alpha huge 2>&1)"
+if [[ $? -eq 2 && "$out" == *usage* ]]; then
+  ok "refuses an unknown bump level"
+else
+  fail "expected usage exit 2, got: $out"
+fi
+git_test_config "$f" checkout -q --detach
+out="$(run_new "$f" alpha patch 2>&1)"
+if [[ $? -eq 2 && "$out" == *"not on a branch"* ]]; then
+  ok "refuses a detached HEAD"
+else
+  fail "expected exit 2 on a detached HEAD, got: $out"
+fi
+rm -rf "$f"
+
+test_harness::report
diff --git a/scripts/release-plugins.sh b/scripts/release-plugins.sh
new file mode 100755
index 0000000000..7e845a9bfd
--- /dev/null
+++ b/scripts/release-plugins.sh
@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+# Turn pending changelog fragments into plugin releases (ADR 0048).
+#
+#   scripts/release-plugins.sh [--date YYYY-MM-DD]
+#
+# For each plugin with fragments under .changes/<plugin>/:
+#   1. the new version is plugin.json's version raised once at the highest
+#      `bump` among the fragments; a plugin whose fragments are all `none` gets
+#      no new version and no CHANGELOG entry;
+#   2. one `## [<new>] - <date>` entry goes above the newest version heading of
+#      plugins/<plugin>/CHANGELOG.md, merging the fragments' bodies section by
+#      section (Keep a Changelog order) in the order the fragments were
+#      committed;
+#   3. `version` changes in plugin.json only;
+#   4. every fragment of the plugin, `none` included, is deleted.
+# Prints one line per plugin. Nothing is written until every fragment and every
+# affected manifest and changelog has been checked. <date> defaults to today in
+# UTC.
+#
+# Fragment order comes from `git log`, so the release job needs the history of
+# .changes/; an uncommitted fragment sorts after every committed one.
+#
+# Exit: 0 released (or nothing pending), 2 usage, an invalid fragment, or a
+# manifest or changelog this script cannot update.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 2
+cd "$SCRIPT_DIR/.." || exit 2
+# shellcheck source=lib/changelog-fragments.sh
+. "$SCRIPT_DIR/lib/changelog-fragments.sh" || exit 2
+
+self="$(basename "$0")"
+date="$(date -u +%Y-%m-%d)"
+if (($# == 2)) && [[ "$1" == --date && "$2" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+  date="$2"
+elif (($# != 0)); then
+  echo "usage: $self [--date YYYY-MM-DD]" >&2
+  exit 2
+fi
+if ! jq --version >/dev/null 2>&1; then
+  echo "$self: jq is required to read manifest versions." >&2
+  exit 2
+fi
+
+fragments=()
+if [[ -d .changes ]]; then
+  mapfile -t fragments < <(find .changes -type f | LC_ALL=C sort)
+fi
+if ((${#fragments[@]} == 0)); then
+  echo "No pending changelog fragments."
+  exit 0
+fi
+for path in "${fragments[@]}"; do
+  changelog_fragments::validate "$path" || {
+    echo "$self: refusing to release while a fragment is invalid." >&2
+    exit 2
+  }
+done
+
+if ! added_log="$(git log --reverse --diff-filter=A --name-only --format= -- .changes/)"; then
+  echo "$self: git log of .changes/ failed; the fragment commit order is unknown." >&2
+  exit 2
+fi
+declare -A order=()
+i=0
+while IFS= read -r path; do
+  [[ -n "$path" ]] || continue
+  i=$((i + 1))
+  order["$path"]=$i
+done <<<"$added_log"
+
+declare -A rank=([none]=0 [patch]=1 [minor]=2 [major]=3)
+declare -A plugin_fragments=() plugin_bump=()
+plugins=()
+for path in "${fragments[@]}"; do
+  rest="${path#.changes/}"
+  name="${rest%%/*}"
+  bump="$(changelog_fragments::bump_of "$path")"
+  if [[ -z "${plugin_bump[$name]:-}" ]]; then
+    plugins+=("$name")
+    plugin_bump["$name"]=none
+  fi
+  if ((rank[$bump] > rank[${plugin_bump[$name]}])); then
+    plugin_bump["$name"]=$bump
+  fi
+  plugin_fragments["$name"]+="$(printf '%08d' "${order[$path]:-99999999}") $bump $path"$'\n'
+done
+
+# Pass 1: compute every new version and check every file it will touch.
+declare -A old_version=() new_version=()
+for name in "${plugins[@]}"; do
+  [[ "${plugin_bump[$name]}" != none ]] || continue
+  manifest="plugins/$name/.claude-plugin/plugin.json"
+  changelog="plugins/$name/CHANGELOG.md"
+  version="$(jq -r '.version // empty' "$manifest" 2>/dev/null)"
+  if [[ ! "$version" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+    echo "$self: $manifest version '$version' is not MAJOR.MINOR.PATCH; cannot raise it." >&2
+    exit 2
+  fi
+  major="${BASH_REMATCH[1]}" minor="${BASH_REMATCH[2]}" patch="${BASH_REMATCH[3]}"
+  case "${plugin_bump[$name]}" in
+  major) new="$((major + 1)).0.0" ;;
+  minor) new="$major.$((minor + 1)).0" ;;
+  *) new="$major.$minor.$((patch + 1))" ;;
+  esac
+  if [[ "$(grep -cE "^[[:space:]]*\"version\"[[:space:]]*:[[:space:]]*\"${version//./\\.}\"" "$manifest")" != 1 ]]; then
+    echo "$self: $manifest does not carry exactly one \"version\": \"$version\" line to rewrite." >&2
+    exit 2
+  fi
+  if [[ ! -f "$changelog" ]]; then
+    echo "$self: $changelog does not exist; refusing to invent one." >&2
+    exit 2
+  fi
+  old_version["$name"]="$version"
+  new_version["$name"]="$new"
+done
+
+# Pass 2: write.
+tmp="$(mktemp)" || exit 2
+entry_file="$(mktemp)" || exit 2
+trap 'rm -f "$tmp" "$entry_file"' EXIT
+for name in "${plugins[@]}"; do
+  mapfile -t ordered < <(printf '%s' "${plugin_fragments[$name]}" | LC_ALL=C sort)
+  paths=()
+  released=()
+  for row in "${ordered[@]}"; do
+    read -r _ bump path <<<"$row"
+    paths+=("$path")
+    [[ "$bump" == none ]] || released+=("$path")
+  done
+
+  if [[ "${plugin_bump[$name]}" == none ]]; then
+    rm -f "${paths[@]}" || exit 2
+    echo "$name: no release; deleted ${#paths[@]} bump: none fragment(s): ${paths[*]}"
+    continue
+  fi
+
+  manifest="plugins/$name/.claude-plugin/plugin.json"
+  changelog="plugins/$name/CHANGELOG.md"
+  old="${old_version[$name]}"
+  new="${new_version[$name]}"
+
+  for path in "${released[@]}"; do
+    changelog_fragments::body "$path" && printf '\f\n'
+  done | awk -v head="## [$new] - $date" -v sections="$CF_SECTIONS" '
+      function flush() {
+        sub(/^\n+/, "", buf); sub(/\n+$/, "", buf)
+        if (cur != "" && buf != "") text[cur] = (cur in text) ? text[cur] "\n\n" buf : buf
+        buf = ""
+      }
+      $0 == "\f" { flush(); cur = ""; next }
+      /^###[ \t]/ { flush(); cur = $0; sub(/^###[ \t]+/, "", cur); sub(/[ \t]+$/, "", cur); next }
+      cur != "" { buf = buf $0 "\n" }
+      END {
+        flush()
+        print head
+        n = split(sections, s, " ")
+        for (i = 1; i <= n; i++) if (s[i] in text) printf "\n### %s\n\n%s\n", s[i], text[s[i]]
+      }
+    ' >"$entry_file" || exit 2
+
+  # The entry is read from a file, not passed with -v, which would expand the
+  # backslash escapes a release note can carry.
+  if ! awk -v ef="$entry_file" '
+    BEGIN { while ((getline line < ef) > 0) entry = entry line "\n" }
+    !done && /^##[ \t]+\[?[0-9]+\.[0-9]+/ { printf "%s\n", entry; done = 1 }
+    { print }
+    END { if (!done) printf "\n%s", entry }
+  ' "$changelog" >"$tmp" || ! cat "$tmp" >"$changelog"; then
+    echo "$self: could not write $changelog." >&2
+    exit 2
+  fi
+
+  if ! awk -v old="\"$old\"" -v new="\"$new\"" '
+    !done && /^[ \t]*"version"[ \t]*:/ && (p = index($0, old)) { $0 = substr($0, 1, p - 1) new substr($0, p + length(old)); done = 1 }
+    { print }
+  ' "$manifest" >"$tmp" || ! cat "$tmp" >"$manifest"; then
+    echo "$self: could not write $manifest." >&2
+    exit 2
+  fi
+  if [[ "$(jq -r '.version' "$manifest")" != "$new" ]]; then
+    echo "$self: rewriting $manifest did not leave version $new." >&2
+    exit 2
+  fi
+
+  rm -f "${paths[@]}" || exit 2
+  echo "$name: $old -> $new (${plugin_bump[$name]}) from ${#paths[@]} fragment(s): ${paths[*]}"
+done
+for name in "${plugins[@]}"; do
+  rmdir ".changes/$name" 2>/dev/null || true
+done
+rmdir .changes 2>/dev/null || true
diff --git a/scripts/release-plugins.test.sh b/scripts/release-plugins.test.sh
new file mode 100755
index 0000000000..a3f5490a59
--- /dev/null
+++ b/scripts/release-plugins.test.sh
@@ -0,0 +1,217 @@
+#!/usr/bin/env bash
+# Unit tests for release-plugins.sh. Each case builds a throwaway git repo with
+# plugins in fragment mode, commits fragments in a known order, runs the release
+# and compares the written CHANGELOG and manifest against literal expectations.
+set -uo pipefail
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$SELF_DIR/release-plugins.sh"
+. "$SELF_DIR/test-git-helpers.sh"
+
+# shellcheck source=lib/test-harness.sh
+. "$SELF_DIR/lib/test-harness.sh"
+# shellcheck source=lib/fixture-tree.sh
+. "$SELF_DIR/lib/fixture-tree.sh"
+
+f=""
+
+# base_fixture <out-var> — alpha 1.2.3 and beta 0.4.0, both in fragment mode.
+base_fixture() {
+  local dir name
+  fixture_tree::build "$1" --sut "$SCRIPT" --git --plugins --label release || return 1
+  dir="${!1}"
+  for name in alpha beta; do
+    mkdir -p "$dir/plugins/$name/.claude-plugin"
+    printf '# Changelog\n\nIntro.\n\n## [0.0.1] - 2026-01-01\n\n### Added\n\n- First.\n' >"$dir/plugins/$name/CHANGELOG.md"
+  done
+  printf '{\n  "name": "alpha",\n  "version": "1.2.3",\n  "options": ["a", "b"]\n}\n' >"$dir/plugins/alpha/.claude-plugin/plugin.json"
+  printf '{\n  "name": "beta",\n  "version": "0.4.0"\n}\n' >"$dir/plugins/beta/.claude-plugin/plugin.json"
+  printf 'alpha\nbeta\n' >"$dir/scripts/fragment-plugins.txt"
+  git_test_config "$dir" add -A
+  git_test_config "$dir" commit -qm base
+}
+
+# add_fragment <fixture> <plugin> <name> <bump> <body> — written and committed.
+add_fragment() {
+  mkdir -p "$1/.changes/$2"
+  printf -- '---\nbump: %s\n---\n\n%s\n' "$4" "$5" >"$1/.changes/$2/$3.md"
+  git_test_config "$1" add -A
+  git_test_config "$1" commit -qm "fragment $3"
+}
+
+run_release() (
+  cd "$1" && bash scripts/release-plugins.sh --date 2026-10-04
+)
+
+# expect_file <label> <path> <expected content>
+expect_file() {
+  local got
+  got="$(cat "$2")"
+  if [[ "$got" == "$3" ]]; then
+    ok "$1"
+  else
+    fail "$1: got
+$got
+--- want
+$3"
+  fi
+}
+
+# --- several fragments: one version at the highest bump, sections merged -------
+base_fixture f
+# Committed z-first so commit order differs from file-name order.
+add_fragment "$f" alpha zeta-11111111 patch "### Fixed
+
+- Zeta fix."
+add_fragment "$f" alpha alpha-22222222 minor "### Added
+
+- Alpha feature.
+
+### Fixed
+
+- Alpha fix."
+add_fragment "$f" alpha mid-33333333 none "Docs only."
+out="$(run_release "$f" 2>&1)"
+rc=$?
+if ((rc == 0)) && [[ "$out" == *"alpha: 1.2.3 -> 1.3.0 (minor) from 3 fragment(s)"* ]]; then
+  ok "raises the version once, at the highest bump among the fragments"
+else
+  fail "expected alpha 1.2.3 -> 1.3.0, got rc=$rc: $out"
+fi
+expect_file "writes one entry, Keep a Changelog section order, fragments in commit order" \
+  "$f/plugins/alpha/CHANGELOG.md" '# Changelog
+
+Intro.
+
+## [1.3.0] - 2026-10-04
+
+### Added
+
+- Alpha feature.
+
+### Fixed
+
+- Zeta fix.
+
+- Alpha fix.
+
+## [0.0.1] - 2026-01-01
+
+### Added
+
+- First.'
+expect_file "changes only the version line of plugin.json" \
+  "$f/plugins/alpha/.claude-plugin/plugin.json" '{
+  "name": "alpha",
+  "version": "1.3.0",
+  "options": ["a", "b"]
+}'
+if [[ ! -e "$f/.changes/alpha" ]]; then
+  ok "deletes every consumed fragment, none included"
+else
+  fail "fragments left behind: $(ls "$f/.changes/alpha")"
+fi
+expect_file "leaves a plugin with no fragments alone" "$f/plugins/beta/.claude-plugin/plugin.json" '{
+  "name": "beta",
+  "version": "0.4.0"
+}'
+rm -rf "$f"
+
+# --- major and patch arithmetic -------------------------------------------------
+base_fixture f
+add_fragment "$f" alpha a-11111111 major "### Removed
+
+- Old thing."
+add_fragment "$f" beta b-22222222 patch "### Fixed
+
+- Beta fix."
+out="$(run_release "$f" 2>&1)"
+if [[ "$out" == *"alpha: 1.2.3 -> 2.0.0"* && "$out" == *"beta: 0.4.0 -> 0.4.1"* ]]; then
+  ok "major resets minor and patch; patch raises patch"
+else
+  fail "expected alpha 2.0.0 and beta 0.4.1, got: $out"
+fi
+rm -rf "$f"
+
+# --- all-none plugin: fragments deleted, no bump, no entry ---------------------
+base_fixture f
+add_fragment "$f" beta b-22222222 none "Test fixture refresh only."
+before="$(cat "$f/plugins/beta/CHANGELOG.md")"
+out="$(run_release "$f" 2>&1)"
+if [[ "$out" == *"beta: no release"* && ! -e "$f/.changes/beta/b-22222222.md" ]]; then
+  ok "deletes a bump: none fragment without releasing"
+else
+  fail "expected the none fragment deleted with no release, got: $out"
+fi
+expect_file "an all-none plugin keeps its version" "$f/plugins/beta/.claude-plugin/plugin.json" '{
+  "name": "beta",
+  "version": "0.4.0"
+}'
+expect_file "an all-none plugin gets no CHANGELOG entry" "$f/plugins/beta/CHANGELOG.md" "$before"
+rm -rf "$f"
+
+# --- a release note keeps its backslashes ---------------------------------------
+base_fixture f
+# shellcheck disable=SC2016  # the backticks are markdown, not command substitution
+add_fragment "$f" beta b-22222222 patch '### Fixed
+
+- Match `a\nb` and `C:\temp` literally.'
+run_release "$f" >/dev/null 2>&1
+# shellcheck disable=SC2016  # see above
+if grep -qF -- '- Match `a\nb` and `C:\temp` literally.' "$f/plugins/beta/CHANGELOG.md"; then
+  ok "copies a fragment body byte for byte, backslashes included"
+else
+  fail "backslashes were rewritten: $(cat "$f/plugins/beta/CHANGELOG.md")"
+fi
+rm -rf "$f"
+
+# --- nothing pending ---------------------------------------------------------------
+base_fixture f
+out="$(run_release "$f" 2>&1)"
+if [[ $? -eq 0 && "$out" == "No pending changelog fragments." ]]; then
+  ok "exits 0 with nothing pending"
+else
+  fail "expected the nothing-pending message, got: $out"
+fi
+rm -rf "$f"
+
+# --- an invalid fragment stops the release before anything is written -----------
+base_fixture f
+add_fragment "$f" alpha a-11111111 minor "### Added
+
+- Fine."
+add_fragment "$f" beta b-22222222 patch "No sections."
+out="$(run_release "$f" 2>&1)"
+rc=$?
+if ((rc == 2)) && grep -q '"version": "1.2.3"' "$f/plugins/alpha/.claude-plugin/plugin.json" && [[ -f "$f/.changes/alpha/a-11111111.md" ]]; then
+  ok "an invalid fragment exits 2 and writes nothing"
+else
+  fail "expected exit 2 and an untouched tree, got rc=$rc: $out"
+fi
+rm -rf "$f"
+
+# --- a plugin not in fragment mode is refused ------------------------------------
+base_fixture f
+printf 'alpha\n' >"$f/scripts/fragment-plugins.txt"
+add_fragment "$f" beta b-22222222 patch "### Fixed
+
+- x"
+out="$(run_release "$f" 2>&1)"
+if [[ $? -eq 2 && "$out" == *"NOT IN FRAGMENT MODE"* ]]; then
+  ok "refuses a fragment for a plugin not in fragment mode"
+else
+  fail "expected exit 2 naming the mode, got: $out"
+fi
+rm -rf "$f"
+
+# --- usage ------------------------------------------------------------------------
+base_fixture f
+out="$(cd "$f" && bash scripts/release-plugins.sh --date tomorrow 2>&1)"
+if [[ $? -eq 2 && "$out" == *usage* ]]; then
+  ok "a malformed --date exits 2"
+else
+  fail "expected usage exit 2, got: $out"
+fi
+rm -rf "$f"
+
+test_harness::report
diff --git a/scripts/sync-shared-copies.sh b/scripts/sync-shared-copies.sh
index 36b172010c..fd898b2874 100755
--- a/scripts/sync-shared-copies.sh
+++ b/scripts/sync-shared-copies.sh
@@ -6,6 +6,8 @@
 #                                                      canonical source generates; never writes
 #   scripts/sync-shared-copies.sh --check-bump <ref>   fail if a canonical changed vs <ref> but a
 #                                                      carrying plugin's manifest version did not
+#                                                      move (or, in fragment mode, it added no
+#                                                      fragment whose bump is not none)
 #   scripts/sync-shared-copies.sh --print-manifest     emit each canonical and its copies as data
 #
 # Each line of scripts/shared-copies.txt registers one copy: `<canonical> <copy>`.
@@ -17,6 +19,8 @@ script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 cd "$script_dir/.."
 # shellcheck source=lib/gate-entry.sh
 . "$script_dir/lib/gate-entry.sh" || exit 2
+# shellcheck source=lib/changelog-fragments.sh
+. "$script_dir/lib/changelog-fragments.sh" || exit 2
 
 registry="scripts/shared-copies.txt"
 self="scripts/sync-shared-copies.sh"
@@ -144,7 +148,7 @@ check_copy() {
 }
 
 check_bump() {
-  local base="$1" src copy rest manifest base_version head_version stale=0 changed=0 src_changed
+  local base="$1" src copy rest manifest base_version head_version stale=0 changed=0 src_changed rc
   gate_entry::require_base "$base" "error: base ref $base does not resolve to a commit."
   for src in "${srcs[@]}"; do
     src_changed=0
@@ -160,7 +164,11 @@ check_bump() {
       base_version=$(git show "$base:$manifest" 2>/dev/null | jq -r '.version // empty' || true)
       [[ -n "$base_version" ]] || continue
       head_version=$(jq -r '.version // empty' "$manifest")
-      if [[ "$head_version" == "$base_version" ]]; then
+      rc=0
+      # shellcheck disable=SC2310  # the non-zero return IS the answer; rc 2 exits below
+      changelog_fragments::bump_delivered "$base" "${rest%%/*}" "$base_version" "$head_version" || rc=$?
+      ((rc < 2)) || exit 2
+      if ((rc == 1)); then
         echo "STALE VERSION: $src or its copy $copy changed vs $base but $manifest is still $head_version" >&2
         rest="${rest#*/}"
         echo "  A bump that only carries the change gets the CHANGELOG entry: Shared \`$(basename "$src")\` synced (<link to the change>); no change to this plugin's ${rest%%/*}." >&2
diff --git a/scripts/sync-shared-copies.test.sh b/scripts/sync-shared-copies.test.sh
index 95e74007d7..6e734d3d15 100755
--- a/scripts/sync-shared-copies.test.sh
+++ b/scripts/sync-shared-copies.test.sh
@@ -124,6 +124,25 @@ expect "--check-bump fails when only a copy changed" 1 $? "$out"
 LAST_OUTPUT="$out"
 assert_output_contains "--check-bump names the changed copy" "its copy plugins/alpha/lib/esc.mjs changed"
 
+# A fragment carries a carrier's bump only when that carrier is in fragment mode.
+mkdir -p "$root/.changes/alpha" "$root/.changes/beta"
+for name in alpha beta; do
+  printf -- '---\nbump: patch\n---\n\n### Fixed\n\n- Shared esc.mjs synced.\n' >"$root/.changes/$name/sync-esc-0123abcd.md"
+done
+git -C "$root" add -A
+printf 'alpha\n' >"$root/scripts/fragment-plugins.txt"
+printf 'export const esc = (s) => String(s ?? "");\n' >"$root/lib/esc.mjs"
+run >/dev/null
+out="$(run --check-bump "$base")"
+expect "--check-bump still fails for a legacy carrier that has only a fragment" 1 $? "$out"
+LAST_OUTPUT="$out"
+assert_output_contains "--check-bump names the legacy carrier" "its copy plugins/beta/lib/esc.mjs changed"
+if [[ "$out" != *"plugins/alpha/lib/esc.mjs changed"* ]]; then
+  pass "--check-bump accepts a fragment-mode carrier's patch fragment as its bump"
+else
+  bad "--check-bump accepts a fragment-mode carrier's patch fragment as its bump" "$out"
+fi
+
 # --- the executable bit follows the canonical, on regen and in --check ----------
 fixture
 printf '#!/usr/bin/env bash\necho hi\n' >"$root/lib/tool.sh"

From 87feb91e26bf2add2c8fa4fd550367d0ba0a345b Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 4 Oct 2026 15:14:17 -0400
Subject: [PATCH 2/3] fix(scripts): harden fragment creator and release
 ordering from review

- new-changelog-fragment.test.sh: add the shellcheck source directive so
  shellcheck -x exits 0 (SC1091).
- release-plugins.sh refuses a shallow clone with exit 2, since fragment
  commit order cannot be read from it; tested with a depth-1 clone.
- new-changelog-fragment.sh strips leading characters that are not letters
  or digits from the branch slug, and refuses a branch with none, so every
  name it writes passes validation; tested with branches _lead and __.

Part of #6006.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 scripts/new-changelog-fragment.sh      |  5 +++++
 scripts/new-changelog-fragment.test.sh | 17 +++++++++++++++++
 scripts/release-plugins.sh             |  7 ++++++-
 scripts/release-plugins.test.sh        | 20 ++++++++++++++++++++
 4 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/scripts/new-changelog-fragment.sh b/scripts/new-changelog-fragment.sh
index 67a388a443..e7cc9a7dfe 100755
--- a/scripts/new-changelog-fragment.sh
+++ b/scripts/new-changelog-fragment.sh
@@ -48,6 +48,11 @@ fi
 
 slug="${branch,,}"
 slug="${slug//[^a-z0-9._-]/-}"
+slug="${slug#"${slug%%[a-z0-9]*}"}"
+if [[ -z "$slug" ]]; then
+  echo "$self: branch '$branch' has no letter or digit to name the fragment after." >&2
+  exit 2
+fi
 path=".changes/$plugin/$slug-$suffix.md"
 if [[ -e "$path" ]]; then
   echo "$self: $path already exists; run it again for a new suffix." >&2
diff --git a/scripts/new-changelog-fragment.test.sh b/scripts/new-changelog-fragment.test.sh
index b82114afd9..f782fed897 100755
--- a/scripts/new-changelog-fragment.test.sh
+++ b/scripts/new-changelog-fragment.test.sh
@@ -52,6 +52,7 @@ else
   fail "unexpected content: $(cat "$f/$first")"
 fi
 printf '### Added\n\n- New thing.\n' >>"$f/$first"
+# shellcheck source=lib/changelog-fragments.sh
 if (cd "$f" && . scripts/lib/changelog-fragments.sh && changelog_fragments::validate "$first"); then
   ok "a created fragment, once filled in, passes validation"
 else
@@ -78,6 +79,22 @@ if [[ $? -eq 2 && "$out" == *usage* ]]; then
 else
   fail "expected usage exit 2, got: $out"
 fi
+git_test_config "$f" checkout -qb _lead
+lead="$(run_new "$f" alpha patch)"
+[[ -f "$f/$lead" ]] && printf '### Fixed\n\n- x\n' >>"$f/$lead"
+# shellcheck source=lib/changelog-fragments.sh
+if [[ "$lead" =~ ^\.changes/alpha/lead-[0-9a-f]{8}\.md$ ]] && (cd "$f" && . scripts/lib/changelog-fragments.sh && changelog_fragments::validate "$lead"); then
+  ok "strips a leading non-alphanumeric so the slug passes validation"
+else
+  fail "expected .changes/alpha/lead-<hex>.md that validates, got: $lead"
+fi
+git_test_config "$f" checkout -qb __
+out="$(run_new "$f" alpha patch 2>&1)"
+if [[ $? -eq 2 && "$out" == *"no letter or digit"* ]]; then
+  ok "refuses a branch with no letter or digit"
+else
+  fail "expected exit 2 for branch __, got: $out"
+fi
 git_test_config "$f" checkout -q --detach
 out="$(run_new "$f" alpha patch 2>&1)"
 if [[ $? -eq 2 && "$out" == *"not on a branch"* ]]; then
diff --git a/scripts/release-plugins.sh b/scripts/release-plugins.sh
index 7e845a9bfd..576e4b1ff6 100755
--- a/scripts/release-plugins.sh
+++ b/scripts/release-plugins.sh
@@ -18,7 +18,8 @@
 # UTC.
 #
 # Fragment order comes from `git log`, so the release job needs the history of
-# .changes/; an uncommitted fragment sorts after every committed one.
+# .changes/ and refuses a shallow clone; an uncommitted fragment sorts after
+# every committed one.
 #
 # Exit: 0 released (or nothing pending), 2 usage, an invalid fragment, or a
 # manifest or changelog this script cannot update.
@@ -57,6 +58,10 @@ for path in "${fragments[@]}"; do
   }
 done
 
+if [[ "$(git rev-parse --is-shallow-repository 2>/dev/null)" == true ]]; then
+  echo "$self: this clone is shallow, so the order the fragments were committed in is unknown; fetch the full history (fetch-depth: 0) and run again." >&2
+  exit 2
+fi
 if ! added_log="$(git log --reverse --diff-filter=A --name-only --format= -- .changes/)"; then
   echo "$self: git log of .changes/ failed; the fragment commit order is unknown." >&2
   exit 2
diff --git a/scripts/release-plugins.test.sh b/scripts/release-plugins.test.sh
index a3f5490a59..583cbd1146 100755
--- a/scripts/release-plugins.test.sh
+++ b/scripts/release-plugins.test.sh
@@ -204,6 +204,26 @@ else
 fi
 rm -rf "$f"
 
+# --- a shallow clone is refused, since commit order is unknown -------------------
+base_fixture f
+add_fragment "$f" alpha a-11111111 minor "### Added
+
+- x"
+add_fragment "$f" alpha b-22222222 patch "### Fixed
+
+- y"
+g=""
+fixture_tree::build g --label release-shallow || exit 2
+git clone -q --depth 1 "file://$f" "$g/repo" 2>/dev/null
+out="$(cd "$g/repo" && bash scripts/release-plugins.sh --date 2026-10-04 2>&1)"
+rc=$?
+if ((rc == 2)) && [[ "$out" == *"shallow"* ]] && grep -q '"version": "1.2.3"' "$g/repo/plugins/alpha/.claude-plugin/plugin.json"; then
+  ok "refuses a shallow clone with exit 2 and writes nothing"
+else
+  fail "expected exit 2 naming the shallow clone, got rc=$rc: $out"
+fi
+rm -rf "$f" "$g"
+
 # --- usage ------------------------------------------------------------------------
 base_fixture f
 out="$(cd "$f" && bash scripts/release-plugins.sh --date tomorrow 2>&1)"

From aae8f8e75c52c9246a0ae78c6dbc8d173512f1f7 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Sun, 4 Oct 2026 15:30:49 -0400
Subject: [PATCH 3/3] fix(scripts): catch edited consumed fragments and stage
 release writes

- check-changelog-fragments.sh --check-release fails with EDITED FRAGMENT
  when a fragment the release consumed differs on the base from the blob at
  the release's merge base, since the release aggregated the older content.
- release-plugins.sh produces every new CHANGELOG and manifest in a temporary
  directory and changes the tree only after all of them exist, so a failure
  while producing a later plugin leaves the tree unchanged. A changelog that
  already carries the version about to be written (a run cut short) is
  refused instead of getting a second entry.

Part of #6006.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 scripts/check-changelog-fragments.sh      | 18 +++++--
 scripts/check-changelog-fragments.test.sh | 11 +++++
 scripts/release-plugins.sh                | 60 ++++++++++++++++-------
 scripts/release-plugins.test.sh           | 35 +++++++++++++
 4 files changed, 102 insertions(+), 22 deletions(-)

diff --git a/scripts/check-changelog-fragments.sh b/scripts/check-changelog-fragments.sh
index 92fae27545..e2589bc096 100755
--- a/scripts/check-changelog-fragments.sh
+++ b/scripts/check-changelog-fragments.sh
@@ -12,7 +12,8 @@
 #       <base-ref>
 #   scripts/check-changelog-fragments.sh --check-release <base-ref>
 #       for the release pull request: <base-ref> holds no fragment this release
-#       left unconsumed for a plugin whose version it bumps
+#       left unconsumed for a plugin whose version it bumps, and no fragment it
+#       consumed has changed on <base-ref> since the release was cut
 #
 # Shipped files are everything under plugins/<name>/ except CHANGELOG.md and a
 # plugin.json edit to `version` alone: those two are what a release writes, so
@@ -161,8 +162,19 @@ for name in "${!bumped[@]}"; do
     exit 2
   fi
   while IFS= read -r path; do
-    [[ -n "$path" && -z "${consumed[$path]:-}" ]] || continue
-    echo "UNCONSUMED FRAGMENT: $path is on $base but this release bumps $name without it; rebuild the release from $base." >&2
+    [[ -n "$path" ]] || continue
+    if [[ -n "${consumed[$path]:-}" ]]; then
+      # Consumed, but only the content the release was cut from: an edit on the
+      # base since then is a change the release never aggregated.
+      if ! base_blob="$(git ls-tree "$base" -- "$path")" || ! cut_blob="$(git ls-tree "$merge_base" -- "$path")"; then
+        echo "$self: 'git ls-tree' failed reading $path; refusing to pass without checking." >&2
+        exit 2
+      fi
+      [[ "$base_blob" != "$cut_blob" ]] || continue
+      echo "EDITED FRAGMENT: $path changed on $base after this release consumed it; rebuild the release from $base." >&2
+    else
+      echo "UNCONSUMED FRAGMENT: $path is on $base but this release bumps $name without it; rebuild the release from $base." >&2
+    fi
     findings=$((findings + 1))
   done <<<"$pending"
 done
diff --git a/scripts/check-changelog-fragments.test.sh b/scripts/check-changelog-fragments.test.sh
index 88bbb8781a..d2a8248cea 100755
--- a/scripts/check-changelog-fragments.test.sh
+++ b/scripts/check-changelog-fragments.test.sh
@@ -226,6 +226,17 @@ else
 fi
 rm -rf "$f"
 
+base_fixture f alpha
+release_branch "$f"
+git_test_config "$f" checkout -q main
+fragment "$f" alpha feat-x-0123abcd minor "### Added
+
+- Reworded after the release was cut."
+commit "$f" edit-consumed
+git_test_config "$f" checkout -q release/plugins
+expect "--check-release fails when a consumed fragment was edited on the base after the cut" 1 "EDITED FRAGMENT: .changes/alpha/feat-x-0123abcd.md" "$f" --check-release main
+rm -rf "$f"
+
 # --- usage ------------------------------------------------------------------------
 base_fixture f alpha
 expect "no arguments exits 2" 2 "usage" "$f"
diff --git a/scripts/release-plugins.sh b/scripts/release-plugins.sh
index 576e4b1ff6..48e1134e91 100755
--- a/scripts/release-plugins.sh
+++ b/scripts/release-plugins.sh
@@ -13,9 +13,10 @@
 #      committed;
 #   3. `version` changes in plugin.json only;
 #   4. every fragment of the plugin, `none` included, is deleted.
-# Prints one line per plugin. Nothing is written until every fragment and every
-# affected manifest and changelog has been checked. <date> defaults to today in
-# UTC.
+# Prints one line per plugin. Every new changelog and manifest is produced in a
+# temporary directory first, and the tree changes only once all of them exist.
+# A changelog that already carries the version about to be written (a run cut
+# short) is refused. <date> defaults to today in UTC.
 #
 # Fragment order comes from `git log`, so the release job needs the history of
 # .changes/ and refuses a shallow clone; an uncommitted fragment sorts after
@@ -116,14 +117,22 @@ for name in "${plugins[@]}"; do
     echo "$self: $changelog does not exist; refusing to invent one." >&2
     exit 2
   fi
+  if grep -qF -- "## [$new]" "$changelog"; then
+    echo "$self: $changelog already has a '## [$new]' entry, so an earlier release run was cut short; restore the tree (git checkout -- .) and run again." >&2
+    exit 2
+  fi
   old_version["$name"]="$version"
   new_version["$name"]="$new"
 done
 
-# Pass 2: write.
-tmp="$(mktemp)" || exit 2
-entry_file="$(mktemp)" || exit 2
-trap 'rm -f "$tmp" "$entry_file"' EXIT
+# Pass 2: produce every new file under $stage. Nothing in the tree changes until
+# all of them exist, so a failure here leaves the tree as it was.
+stage="$(mktemp -d)" || exit 2
+trap 'rm -rf "$stage"' EXIT
+targets=()
+staged=()
+deletions=()
+report=()
 for name in "${plugins[@]}"; do
   mapfile -t ordered < <(printf '%s' "${plugin_fragments[$name]}" | LC_ALL=C sort)
   paths=()
@@ -135,8 +144,8 @@ for name in "${plugins[@]}"; do
   done
 
   if [[ "${plugin_bump[$name]}" == none ]]; then
-    rm -f "${paths[@]}" || exit 2
-    echo "$name: no release; deleted ${#paths[@]} bump: none fragment(s): ${paths[*]}"
+    deletions+=("${paths[@]}")
+    report+=("$name: no release; deleted ${#paths[@]} bump: none fragment(s): ${paths[*]}")
     continue
   fi
 
@@ -162,35 +171,48 @@ for name in "${plugins[@]}"; do
         n = split(sections, s, " ")
         for (i = 1; i <= n; i++) if (s[i] in text) printf "\n### %s\n\n%s\n", s[i], text[s[i]]
       }
-    ' >"$entry_file" || exit 2
+    ' >"$stage/$name.entry" || exit 2
 
   # The entry is read from a file, not passed with -v, which would expand the
   # backslash escapes a release note can carry.
-  if ! awk -v ef="$entry_file" '
+  if ! awk -v ef="$stage/$name.entry" '
     BEGIN { while ((getline line < ef) > 0) entry = entry line "\n" }
     !done && /^##[ \t]+\[?[0-9]+\.[0-9]+/ { printf "%s\n", entry; done = 1 }
     { print }
     END { if (!done) printf "\n%s", entry }
-  ' "$changelog" >"$tmp" || ! cat "$tmp" >"$changelog"; then
-    echo "$self: could not write $changelog." >&2
+  ' "$changelog" >"$stage/$name.changelog"; then
+    echo "$self: could not produce the new $changelog." >&2
     exit 2
   fi
 
   if ! awk -v old="\"$old\"" -v new="\"$new\"" '
     !done && /^[ \t]*"version"[ \t]*:/ && (p = index($0, old)) { $0 = substr($0, 1, p - 1) new substr($0, p + length(old)); done = 1 }
     { print }
-  ' "$manifest" >"$tmp" || ! cat "$tmp" >"$manifest"; then
-    echo "$self: could not write $manifest." >&2
+  ' "$manifest" >"$stage/$name.manifest"; then
+    echo "$self: could not produce the new $manifest." >&2
     exit 2
   fi
-  if [[ "$(jq -r '.version' "$manifest")" != "$new" ]]; then
-    echo "$self: rewriting $manifest did not leave version $new." >&2
+  if [[ "$(jq -r '.version' "$stage/$name.manifest" 2>/dev/null)" != "$new" ]]; then
+    echo "$self: rewriting $manifest did not leave version $new; nothing was written." >&2
     exit 2
   fi
 
-  rm -f "${paths[@]}" || exit 2
-  echo "$name: $old -> $new (${plugin_bump[$name]}) from ${#paths[@]} fragment(s): ${paths[*]}"
+  targets+=("$changelog" "$manifest")
+  staged+=("$stage/$name.changelog" "$stage/$name.manifest")
+  deletions+=("${paths[@]}")
+  report+=("$name: $old -> $new (${plugin_bump[$name]}) from ${#paths[@]} fragment(s): ${paths[*]}")
+done
+
+# Pass 3: apply. Changelogs and manifests first and fragments last, so a run
+# cut short here is caught by the existing-entry check above on the next run.
+for i in "${!targets[@]}"; do
+  if ! cat "${staged[i]}" >"${targets[i]}"; then
+    echo "$self: could not write ${targets[i]}; restore the tree (git checkout -- .) before running again." >&2
+    exit 2
+  fi
 done
+rm -f "${deletions[@]}" || exit 2
+printf '%s\n' "${report[@]}"
 for name in "${plugins[@]}"; do
   rmdir ".changes/$name" 2>/dev/null || true
 done
diff --git a/scripts/release-plugins.test.sh b/scripts/release-plugins.test.sh
index 583cbd1146..02df11ee57 100755
--- a/scripts/release-plugins.test.sh
+++ b/scripts/release-plugins.test.sh
@@ -204,6 +204,41 @@ else
 fi
 rm -rf "$f"
 
+# --- a failure producing a later plugin's files leaves the whole tree unchanged ---
+# beta's manifest has one line that starts with "version", but the first match on
+# it is the nested key, so the rewrite misses the top-level version. alpha sorts
+# first and has already been produced when beta fails.
+base_fixture f
+printf '{"name": "beta", "meta": {\n  "version": "0.4.0" }, "version": "0.4.0"}\n' >"$f/plugins/beta/.claude-plugin/plugin.json"
+add_fragment "$f" alpha a-11111111 minor "### Added
+
+- x"
+add_fragment "$f" beta b-22222222 patch "### Fixed
+
+- y"
+out="$(run_release "$f" 2>&1)"
+rc=$?
+if ((rc == 2)) && [[ -z "$(git -C "$f" status --porcelain)" ]]; then
+  ok "a failure producing a later plugin's files exits 2 and leaves the tree unchanged"
+else
+  fail "expected exit 2 and a clean tree, got rc=$rc: $out; status: $(git -C "$f" status --porcelain)"
+fi
+rm -rf "$f"
+
+# --- a rerun after a run cut short does not write a second entry ------------------
+base_fixture f
+add_fragment "$f" alpha a-11111111 minor "### Added
+
+- x"
+printf '\n## [1.3.0] - 2026-10-04\n' >>"$f/plugins/alpha/CHANGELOG.md"
+out="$(run_release "$f" 2>&1)"
+if [[ $? -eq 2 && "$out" == *"already has a '## [1.3.0]' entry"* ]]; then
+  ok "refuses to write a version the changelog already carries"
+else
+  fail "expected exit 2 naming the existing entry, got: $out"
+fi
+rm -rf "$f"
+
 # --- a shallow clone is refused, since commit order is unknown -------------------
 base_fixture f
 add_fragment "$f" alpha a-11111111 minor "### Added