fix(scripts): derive usage() header ranges instead of hardcoded sed

plugins/songwriting/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "songwriting",
-  "version": "1.4.19",
-  "description": "Songwriting craft companion — nine concern-scoped lyric-craft skills (workflow router, rhyme, object-writing, metaphor, meter-prosody, song-form, co-write, diagnose, practice) applying Pat Pattison's methods, with an object-writing agent that performs the sensory exercise itself and per-skill emission boundaries that route generation to the skill that owns it, plus Suno v5.5 prompt engineering (style prompts, tagged lyrics, genre templates, troubleshooting).",
+  "version": "1.4.20",
+  "description": "Songwriting craft companion \u2014 nine concern-scoped lyric-craft skills (workflow router, rhyme, object-writing, metaphor, meter-prosody, song-form, co-write, diagnose, practice) applying Pat Pattison's methods, with an object-writing agent that performs the sensory exercise itself and per-skill emission boundaries that route generation to the skill that owns it, plus Suno v5.5 prompt engineering (style prompts, tagged lyrics, genre templates, troubleshooting).",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"

plugins/songwriting/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to the `songwriting` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [1.4.20]
+
+### Fixed
+
+- **`datamuse.sh --help` prints the whole header, including the Examples block.** `usage()`
+  extracted `sed -n '2,28p'`, so the five example lines that landed on 29-33 never appeared.
+  It now derives the header the same way `babysit-readiness-gate.sh` does (awk to the first
+  non-comment line). `--help` / `-h` exit 0 with that block.
+
 ## [1.4.19]
 
 ### Changed

plugins/songwriting/context/pat-pattison/scripts/datamuse.sh

@@ -39,11 +39,22 @@ MODE="${1:-}"
 shift || true
 ARG="${*:-}"
 
-usage() { sed -n '2,28p' "$0" >&2; }
+# Print the header block (shebang to first non-comment line). Derived rather
+# than a hardcoded sed range, which dropped the Examples lines as the header
+# grew (#3424).
+usage() {
+  awk 'NR == 1 { next } /^#/ { sub(/^# ?/, ""); print; next } { exit }' \
+    "${BASH_SOURCE[0]}" >&2
+}
 
 # jq: emit each result as TSV (word, score, numSyllables, tags).
 emit_tsv() { jq -r '.[] | [.word, (.score // 0), (.numSyllables // 0), ((.tags // []) | join(","))] | @tsv'; }
 
+if [[ "$MODE" == "-h" || "$MODE" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
 if [[ -z "$MODE" || -z "$ARG" ]]; then
   usage
   exit 1

plugins/songwriting/context/pat-pattison/scripts/datamuse.test.sh

@@ -181,9 +181,18 @@ assert_contains "usage banner names the API" "$ERR" "https://www.datamuse.com/ap
 # Narrowing the range drops one or both.
 assert_contains "usage banner reaches the last mode listed" "$ERR" "datamuse.sh family"
 assert_contains "usage banner documents the LIMIT override" "$ERR" "LIMIT=<n>"
+assert_contains "usage banner reaches the Examples block" "$ERR" "datamuse.sh rhyme lonely"
+assert_contains "usage banner includes the LIMIT=50 example" "$ERR" "LIMIT=50 datamuse.sh near grief"
 assert_eq "no arguments issues no request" "0" "$(request_count)"
 assert_eq "no arguments writes nothing to stdout" "" "$OUT"
 
+reset_stub
+run_datamuse --help
+assert_eq "--help -> exit 0" "0" "$RC"
+assert_contains "--help reaches the Examples block" "$ERR" "datamuse.sh rhyme lonely"
+assert_eq "--help issues no request" "0" "$(request_count)"
+assert_eq "--help writes nothing to stdout" "" "$OUT"
+
 reset_stub
 run_datamuse rhyme
 assert_eq "mode without a word -> exit 1" "1" "$RC"

scripts/affected-tests.sh

@@ -237,8 +237,12 @@ STRUCTURAL_BASENAMES="README.md SKILL.md AGENTS.md CLAUDE.md CHANGELOG.md
 plugin.json marketplace.json settings.json hooks.json package.json
 package-lock.json index.md LICENSE"
 
+# Print the header block (everything after the shebang up to the first
+# non-comment line) with its comment markers stripped. Derived rather than a
+# hardcoded line range, which silently truncated as the header grew.
 usage() {
-  sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'
+  awk 'NR == 1 { next } /^#/ { sub(/^# ?/, ""); print; next } { exit }' \
+    "${BASH_SOURCE[0]}"
 }
 
 base_ref=""

scripts/affected-tests.test.sh

@@ -1018,4 +1018,15 @@ else
 fi
 rm -rf "$repo3"
 
+# --- --help reaches the actual end of the header -----------------------------
+# usage() used to extract a hardcoded sed range that stopped mid-header as the
+# comment block grew (#3424). Pin a sentence that lives on the last header
+# lines so a drifted range cannot come back unnoticed.
+help_out="$(bash scripts/affected-tests.sh --help)"
+if printf '%s' "$help_out" | grep -q 'Both stages fail loud'; then
+  ok "--help reaches the end of the header (derived usage)"
+else
+  fail "--help truncated before the header's last sentence: $help_out"
+fi
+
 test_harness::report