ci(release): start generated release notes at the previous tag of the same kind

[mbeacom]

What and why

The Release workflow ran gh release create --generate-notes with no start tag, so GitHub diffed against the latest release of any kind. spec-kit-v0.1.5's notes listed every PR since v0.18.0 (#274 and #277–#282: plugin, CI, docs), and v0.19.0 would have started at spec-kit-v0.1.5, leaving those PRs out of both lockstep releases.

scripts/release-notes-start-tag.ts picks the highest existing tag of the same kind below the one being released, by SemVer: v* for lockstep, <adapter>-v* for adapters. The moving v0, pre-releases, and action-recovery-block/* never match. A first release of a kind passes no start tag (GitHub's default), and an invalid tag fails the step rather than falling back. Bun is already set up in that job, and checkout uses fetch-depth: 0, which a contract test now asserts.

Against this repo's tags it prints v0.18.0 for v0.19.0 and spec-kit-v0.1.5 for spec-kit-v0.1.6. A dry run of the step with a fake gh produced --generate-notes --notes-start-tag v0.18.0 for the lockstep draft.

Checklist

• DCO signed off.
• Recorded decision: n/a. This fixes the release pipeline; RELEASING.md gains one guarantee bullet and one sentence in step 8.
• Schema, packages/ci, or core: n/a.
• Observed failing first (ADR-0016):
  • a dropped kind filter (4 tests failed; in-between versions were added because the first pass didn't fail);
  • string instead of SemVer ordering;
  • the old release.yml, which fails the contract test.
• bun test scripts: 1133 pass. typecheck, lint, check:stale-refs, and check:changelog are clean.

Notes for reviewers

• Gate label: this touches .github/workflows/ and scripts/, so it needs gate-change-acknowledged.
• Merge before v0.19.0 is tagged, so the draft starts at v0.18.0.
• spec-kit-v0.1.5's existing notes get an ordinary edit after v0.19.0 is published, so they point at a release that exists.

[Copilot]

🟢 Approval recommended

The implementation, workflow integration, tests, and documentation consistently address cross-kind release-note boundaries.

0 open findings

What changed in this PR

Ensures generated release notes compare against the previous release tag of the same release kind.

Changes:

• Adds SemVer-aware same-kind tag selection with tests.
• Wires the selected tag into the release workflow.
• Documents the release-note guarantee.

Automated ADR context resolution was unavailable; repository guidance was reviewed directly.

File	Description
scripts/​release-notes-start-tag.ts	Selects the prior same-kind release tag.
scripts/​release-notes-start-tag.test.ts	Tests parsing, filtering, and ordering.
scripts/​action-tag-recovery-contract.test.ts	Verifies release-workflow wiring.
.github/​workflows/​release.yml	Passes the selected start tag to gh.
docs/​RELEASING.md	Documents the updated behavior.

🧠 Review effort: Balanced

[github-actions]

Decisions governing this change

6 accepted decisions govern this change

• 0007 — Isolate integrations as optional adapters and build only against public surfaces
  • via path: .github/workflows/**
• 0010 — Use Bun as the package manager and test runner while publishing Node-targeted artifacts
  • via path: .github/workflows/**
• 0031 — Publish a narrow consumer SDK as the contract, and document the CLI JSON as its sibling
  • via path: docs/RELEASING.md
• 0032 — Publish one lockstep OCI image after the coordinated release succeeds
  • via path: docs/RELEASING.md
• 0035 — Execute the gates that certify a pull request from the default branch
  • via path: .github/workflows/**
  • via path: scripts/**
• 0036 — Expose the governing-decisions Action through one root Marketplace entry point
  • via path: .github/workflows/release.yml
  • via path: docs/RELEASING.md

_{Links point at 793166f, this run's GITHUB_SHA. Run adr explain <path> locally to see why a file is governed.}