v2.3.0

v2.3.0

Minor release. Adds a fifth mode: the skill now writes the release note for a version
from what actually landed since the last release. MINOR rather than PATCH because the new
mode is new functionality. Every request that worked in 2.2.0 behaves identically here —
mode 4 gains the ability to publish a release, but only behind a further explicit ask —
and the read-only guarantee that governed modes 1–3 now covers mode 5 as well.

Release notes, grounded in the range

The note is built from the diff, not the commit subjects. Mode 5 establishes the range
from the last version tag reachable from HEAD, then reads git diff <base>..HEAD across
it. A commit whose message understated what it shipped doesn't get to understate it a
second time in the release note.

Tags are fetched first. A local tag list goes stale silently, and it goes stale most
often in exactly the repos that use this workflow: gh release create makes the tag on the
remote, so a machine that hasn't fetched since the last release doesn't have it. Skipping
the fetch produces a note for the wrong range that looks entirely correct.

A tag/version-field disagreement is reported, never resolved silently. When the last
tag and the project's version field disagree, the note says so and states which one it used
as the range base. The usual cause is benign — the field was bumped for the release you're
about to cut — but a tag ahead of the field means a release went out without one, which
is worth knowing before the next one does.

Entries are grouped by user-visible effect, not by file and not by commit. Several
commits delivering one change get one entry; internal churn that changes no behaviour is
left out unless it affects how someone uses or installs the project. Every line traces to a
real commit or hunk, and the commit-body discipline from 2.1.1 governs all of them — no
diff narration, no generic value claims, no invented rationale.

It won't invent your versioning scheme

If the repository has no versioning at all — no version-shaped tags, no version field,
no releases — mode 5 says so and stops. It will not create the repository's first-ever tag.
Whether a project uses SemVer or CalVer, whether tags carry a v prefix, and where the
canonical number lives are all decisions that a first tag settles silently, and they belong
to the maintainer. An unversioned summary of what changed is offered instead.

Your release style wins

Prior releases outrank the built-in template. Mode 5 detects tag prefix (v2.3.0 vs
2.3.0), title shape, heading levels, section names and their order, and bullet style from
gh release view or an existing CHANGELOG.md / RELEASE*.md, and follows them wherever
they conflict with the template — noting the deviation once rather than quietly
reformatting the project's release history.

The template is only the fallback for a repo with no release history: Breaking changes
first, because it's the thing a reader must not miss, then Added / Changed / Fixed /
Removed / Deprecated / Security / Upgrade notes / Full changelog. Sections with nothing
real in them are dropped rather than padded with "N/A" or "None", and the compare link is
emitted only when both tags actually resolve — no dead links.

Mode 4 can publish

Only on a further explicit request. Producing a release note is not a request to publish
one, and neither is approving the note you were just shown. Publishing takes mode 4 and an
explicit ask to publish, together.

gh is checked before anything else (command -v gh, gh auth status). If either check
fails, the note falls back to a Markdown block in the conversation and says which one
failed — an unavailable gh is never a reason to stop, because the note is the deliverable
and publishing is a convenience on top of it.

Hard limits. An existing tag or release for the version is never overwritten or moved —
mode 4 stops and reports it. No --force, no deleting a tag or a release. Mode 4's other
constraints are unchanged: it still never opens pull requests, still never force-pushes,
still never git add -A.

allowed-tools gains Bash(gh:*) for this. Without the grant, publishing degrades into the
read-only fallback instead of erroring, which makes a missing grant look exactly like an
uninstalled gh.

Files updated

• SKILL.md — version bump to 2.3.0; allowed-tools gains Bash(gh:*); mode 5 added to
  the mode contract and the ground rules; a mode 5 section; mode 4 extended with publishing
  and its limits; the reference list is now six files.
• references/release-notes.md — new. The versioning precondition, range establishment,
  style detection, the fallback template, content rules, output targets, and the gh
  publish workflow with its hard limits.
• AGENTS.md — mode 5 and the mode 4 publishing extension, written self-contained.
• README.md — five modes throughout; mode 5 documented in the Use section with example
  output; gh noted as an optional dependency with its fallback; layout tree updated.
• GEMINI.md, .cursor/rules/git-authoring.mdc — mode contract and release-note rules
  updated; both still defer to AGENTS.md for detail.

Upgrade notes

Drop-in replacement for 2.2.0. The no-attribution default from 2.2.0 is untouched, and every
request that worked before behaves the same way now. Two things worth knowing: the read-only
guarantee now reads "modes 1–3 and 5", and gh is a new optional dependency — mode 5
uses it to detect your prior release style, and mode 4 needs it to publish, but the skill
degrades to Markdown output without it and tells you which check failed.

Full Changelog: v2.2.0...v2.3.0