chore: patch release-manager skill with v0.5.0 lessons learned

[wjduenow]

Patches .claude/skills/release-manager/SKILL.md with five edits, each capturing one mistake from cutting v0.5.0:

1. Pre-flight branch check — recognise the dev-ahead-of-main case (common when main is at v(N-1) and dev carries v(N) work). Skill previously required main; now detects the deviation and points to Step 3's two-shape guidance.
2. Pre-flight item 5 — stale-[Unreleased] carryover guard — diff [Unreleased] against the previous [X.(Y-1).0] section; identical → STOP. This is the load-bearing check that would have caught v0.5.0's "release notes byte-identical to v0.4.0" bug at pre-flight time instead of at PR-merge-conflict time. Linked to Step 9's cleanup as the long-term fix.
3. Step 1 — skill metadata lockstep bump — signalforge-version stamps in src/signalforge/skills/signalforge/SKILL.md frontmatter and assets/SKILL.eval.json must match __version__ (and bump in lockstep at every version edit). v0.5.0 shipped without these bumps on the first attempt; the patched skill grep+edits both.
4. Step 3 — dev-ahead-of-main branching shape — two variants documented inline. Normal case = branch from main. Dev-ahead case = branch from main + cherry-pick the post-v(N-1) commits (often a single squash-merge). Verification recipe: git diff release/X.Y.Z origin/dev --stat should show only the release-prep edits.
5. Steps 8 + 9 combined — one PR per release-cycle housekeeping pass (next-dev bump + skill metadata + backmerge + CHANGELOG cleanup). Crucially: git checkout --theirs CHANGELOG.md during the merge resets dev to main's clean post-release shape, which is what prevents pre-flight item 5 from firing next cycle. The old separate-PR shape (Step 8 = bump, Step 9 = backmerge) loses signal when dev is ahead.

Also bumps the skill's own signalforge-version metadata 0.1.0 → 0.5.0 (was stale from when the skill was authored).

Scope note: .claude/skills/release-manager/ is a maintainer-only skill — outside src/, excluded from the wheel by Hatch construction (the [tool.hatch.build.targets.wheel].include directive scopes to src/signalforge/skills). So this PR touches only the local dev experience; nothing ships to PyPI users.

Memory cross-link: `release-clear-unreleased-on-backmerge` (the load-bearing CHANGELOG cleanup, now codified in Step 9 itself) and `release-full-from-dev-ahead-of-main` (the parent shape).

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation

• Release management enhancements – Updated release process documentation to v0.5.0 with improved branching detection, changelog validation guards, coordinated version and metadata updates, and streamlined release workflows to ensure reliable and consistent releases.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates the release-manager skill documentation to version 0.5.0, enhancing the full-release workflow with dev-ahead detection, stale CHANGELOG guards, skill metadata version bumping, reworked branching logic in Step 3, and a consolidated dev PR that replaces separate Steps 8 and 9.

Changes

Release-manager workflow procedural updates

Layer / File(s)	Summary
Skill version alignment to 0.5.0 .claude/skills/release-manager/SKILL.md	Bumped the skill's frontmatter signalforge-version metadata from 0.1.0 to 0.5.0 to align the skill version with the release target.
Pre-flight validation enhancements for dev-ahead and stale CHANGELOG detection .claude/skills/release-manager/SKILL.md	Enhanced full-release pre-flight logic to detect when dev is ahead of main (via git log origin/main..origin/dev) and redirect workflow to proceed from dev; added a full-release-only guard that compares CHANGELOG [Unreleased] sections and stops on byte-identical duplicates to prevent stale carryover; updated pre-flight summary output to report both checks.
Release prep and Step 3 rework with skill metadata bumping and branching logic .claude/skills/release-manager/SKILL.md	Added instruction block to bump skill metadata in lockstep during full-release prep, grepping and updating both bundled SKILL.md and SKILL.eval.json to the release version; reworked Step 3 release-PR guidance to include two explicit branching shapes (normal vs. dev-ahead), dev-ahead cherry-pick workflow, explicit diff verification expectation, and updated PR opening instructions to reflect combined release-prep edits.
Consolidated dev PR and checklist update .claude/skills/release-manager/SKILL.md	Replaced separate Steps 8 and 9 with a single combined dev PR that bumps __version__ and skill metadata, merges main into dev, and resolves CHANGELOG conflicts by taking main's post-release shape via git checkout --theirs; updated surrounding narrative with validation, commit, push, and PR steps; updated "Done" checklist to confirm the combined Steps 8+9 PR is open or merged.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• wjduenow/SignalForge#174: Both PRs update release-version metadata (signalforge-version/version fields) and CHANGELOG handling around the 0.5.0→0.6.0 release line, overlapping on version and skill-metadata areas.

Poem

🐰 A release flows smooth, when paths align,
Dev ahead? Main behind? We'll sort this fine,
Metadata bumps in lockstep dance,
One PR now, where two had their chance. 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: patching the release-manager skill documentation with lessons from v0.5.0 release, matching the PR's core objective of codifying five edits that address mistakes encountered during that release cycle.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

🧹 Nitpick comments (2)

.claude/skills/release-manager/SKILL.md (2)

241-248: 💤 Low value

Consider adding explicit main checkout for consistency.

The normal case assumes you're on main but doesn't show the checkout step, while the dev-ahead case (line 253) explicitly shows git checkout main && git pull origin main. Adding the same explicit checkout to the normal case would make the two shapes more symmetric and reduce ambiguity.

♻️ Proposed addition

 **(a) Normal case (main has the release content)** — branch from main:
 
 ```bash
+git checkout main && git pull origin main
 git checkout -b release/{release_version}

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/skills/release-manager/SKILL.md around lines 241 - 248, Update the
"Normal case (main has the release content)" snippet to explicitly ensure you're
on and up-to-date with main before creating the release branch; insert a step
that runs "git checkout main && git pull origin main" immediately before the
"git checkout -b release/{release_version}" command so the normal-case flow
mirrors the dev-ahead case and removes ambiguity about the current branch.

---

59-59: ⚡ Quick win

Verify the version-parsing pattern works beyond 0.x releases.

The pattern grep '^## \[0\.' assumes all versions start with "0." — this will break when SignalForge reaches 1.0.0.

♻️ Proposed fix to match any semver version

-   awk -v ver="$(grep '^## \[0\.' CHANGELOG.md | sed -n 2p | sed -E 's/^## \[([^]]+)\].*/\1/')" \
+   awk -v ver="$(grep '^## \[[0-9]' CHANGELOG.md | sed -n 2p | sed -E 's/^## \[([^]]+)\].*/\1/')" \

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.claude/skills/release-manager/SKILL.md at line 59, The current changelog
version extraction uses grep '^## \[0\.' which only matches 0.x versions; update
the grep/sed pattern in the AWK line to match any semantic version (e.g., use
grep -E '^## \[[0-9]+\.[0-9]+\.[0-9]+' and keep the sed -E 's/^##
\[([^]]+)\].*/\1/' to capture the version) so the awk -v ver="(…)" assignment
will work for 1.0.0 and beyond.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In @.claude/skills/release-manager/SKILL.md:
- Around line 241-248: Update the "Normal case (main has the release content)"
snippet to explicitly ensure you're on and up-to-date with main before creating
the release branch; insert a step that runs "git checkout main && git pull
origin main" immediately before the "git checkout -b release/{release_version}"
command so the normal-case flow mirrors the dev-ahead case and removes ambiguity
about the current branch.
- Line 59: The current changelog version extraction uses grep '^## \[0\.' which
only matches 0.x versions; update the grep/sed pattern in the AWK line to match
any semantic version (e.g., use grep -E '^## \[[0-9]+\.[0-9]+\.[0-9]+' and keep
the sed -E 's/^## \[([^]]+)\].*/\1/' to capture the version) so the awk -v
ver="(…)" assignment will work for 1.0.0 and beyond.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 47c2c23d-4ef3-496b-a17d-3e4954904ba9

📥 Commits

Reviewing files that changed from the base of the PR and between 89d838a and 9cdc2c2.

📒 Files selected for processing (1)

• .claude/skills/release-manager/SKILL.md