chore(release): author release notes in .changes instead of reconstructing them (#1256)

* chore(release): author release notes in .changes instead of reconstructing them

CHANGELOG.md has been frozen at 0.12.0 since 2023 while the app shipped
0.23.0, semantic-release sat in devDependencies with no config, and the real
user-facing notes were a 280-line MDX post written from memory at release
time. The gap was never version math — it was authored notes captured while
the context is still fresh.

Add a `.changes/*.md` note format (type, area, issues, screenshot; no version
field, since the release version is chosen deliberately) plus a generator that
composes the GitHub release body, the CHANGELOG.md section and a blog-post
scaffold from the accumulated notes.

Changesets was considered and rejected: it versions multiple published
packages, and this repo has exactly one private package. Its `version` step
would also rewrite CHANGELOG.md into a flatter format than the blog post and
fight the deliberate, updater-constrained version choice.

- hand-rolled frontmatter parser over a YAML engine: the schema is closed, so
  it can reject unknown keys, which is what catches typos
- PR numbers are resolved from the commit that added the note, never written
  by the author
- MDX-significant characters in note bodies are escaped so a stray `<` cannot
  break the website build
- blog scaffold ships `draft: true` with explicit TODO headings; the prose is
  editorial work, only the inventory is mechanical
- revive CHANGELOG.md with an honest pointer for 0.13.0-0.23.0 rather than
  fabricating the missing history
- drop the five unused semantic-release/conventional-changelog packages

Docs: `.changes/README.md`, plus a "Release Notes For User-Visible Changes"
section mirrored in CLAUDE.md and AGENTS.md, and a PR template checkbox for
contributors who never read either.

Tests: 26 unit tests in tools/release/release-notes.test.mjs covering parsing,
validation, grouping and all three renderers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(release): default the notes version to package.json and harden alt escaping

Review follow-ups on the release-notes generator.

- `--version` now defaults to the root package.json version, so the
  `release🎶*` package scripts run bare instead of failing on a missing
  argument. Bumping package.json is the deliberate act that starts a release,
  which makes it the right single source of truth; `--version` remains as an
  override for dry runs before the bump. The notice goes to stderr so
  `--format github` keeps a pipeable stdout.
- Escape backslashes before apostrophes when building the MDX `alt` string
  literal. A note body ending in a backslash previously produced an
  unterminated string and would have broken the website build.
- Document that release posts are one per minor version, in the slug helper,
  the overwrite error, and `.changes/README.md` — a patch release edits the
  existing post rather than creating a second one.

Tests: +1 regression test for the alt escaping, verified to fail without the
fix (27 total, all passing).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* feat(ci): put authored notes into the tag release body, fail-closed

Wires the .changes pipeline into the release workflow (Codex review P1 on
#1256). Calling the generator from the tag build cannot work — --consume
deletes .changes/ before the tag exists — so the tag build reads what the
generator already wrote: release-meta now fills BODY from the CHANGELOG.md
section matching the tag's version via tools/release/extract-changelog-section.mjs.

generate_release_notes stays on, so GitHub's commit list renders below the
authored notes; the existing draft-metadata repair step already concatenates
RELEASE_BODY with the generated notes, so the rare duplicate-draft path keeps
the same layering unchanged.

The extractor exits non-zero when the section is missing or empty, failing
the release instead of silently shipping PR-title-only notes. A hotfix tag
cut without running release:notes:changelog therefore fails at create-release
by design; the error message names the exact commands to run.

Tests: 5 new extractor tests (32 total in release-tools, all passing);
packaging suite (247) re-run green since build-and-make.yaml is one of its
inputs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(release): escape all regex metacharacters in the changelog extractor

CodeQL flagged the version-to-RegExp interpolation in
extract-changelog-section.mjs (regex injection + incomplete escaping): only
dots were escaped, and while the CLI validates its argument as bare semver
before calling, the exported extractSection() carries no such guarantee on
its own. Escape the full metacharacter set so no caller can inject pattern
syntax, with tests covering wildcard dots, alternation, `.*` and backslashes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(release): make changelog generation idempotent per version

Codex review P2 on #1256: rerunning `release:notes:changelog` for the same
version — the normal move after correcting a note before --consume —
prepended a second section instead of replacing the first, leaving duplicate
release entries.

Extract the marker insertion into upsertChangelogSection(): it removes any
existing section for the version, then rebuilds around the marker rather than
string-replacing into it, so the blank-line count on both sides stays exact
on both the fresh-insert and replace paths. The CLI reports when a section
was replaced.

Tests: 4 new cases (insert, replace-not-duplicate, neighbours untouched,
missing marker); 37 total passing. End-to-end rerun verified: one heading,
latest date wins, extractor output unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

.changes/README.md

@@ -0,0 +1,86 @@
+# Release notes (`.changes/`)
+
+Every PR with a user-visible change drops one file here describing that change
+in plain language. At release time
+`tools/release/build-release-notes.mjs` turns the accumulated files into the
+GitHub release body, the `CHANGELOG.md` section, and a blog-post scaffold for
+the website — then deletes them.
+
+The point is to write the note **while the context is still fresh**, instead of
+reconstructing three months of work from commit titles at release time.
+
+## File
+
+Name it `<area>-<short-slug>.md`, e.g. `.changes/playback-up-next-rail.md`.
+
+```markdown
+---
+type: feature
+area: playback
+issues: [1187]
+screenshot: up-next-rail
+---
+
+Series now show an "Up Next" rail beside the player on wide windows: the rest
+of the current season, watch progress, and click-to-play inline.
+```
+
+| Field        | Required | Value                                                       |
+| ------------ | -------- | ----------------------------------------------------------- |
+| `type`       | yes      | `breaking`, `feature`, `fix`, `perf`, or `internal`          |
+| `area`       | yes      | lowercase slug, same as the conventional-commit scope        |
+| `issues`     | no       | issue numbers this closes — `[1187]` or `1187`               |
+| `screenshot` | no       | slug from the release screenshot manifest                    |
+
+There is **no version field**. The release version is chosen deliberately at
+release time, not derived from these files.
+
+You never write a PR number: the generator resolves it from the commit that
+added the file.
+
+## Writing the body
+
+One to three sentences, present tense, **written for a user, not a reviewer**.
+The body is capped at 400 characters — depth belongs in the blog post.
+
+- ❌ "Refactor `WebVideoControlsAdapter` to hoist volume state into the session"
+- ✅ "The player now remembers volume between episodes"
+
+- ❌ "Fix off-by-one in `resolveEnrichmentSeasonNumber`"
+- ✅ "Series whose title carries a season marker no longer show the wrong season"
+
+`type: internal` is for changes with no user-visible effect that are still worth
+recording (dependency bumps with behaviour risk, packaging moves). They stay out
+of the release body and blog post, and land collapsed in `CHANGELOG.md`.
+
+## When a note is not needed
+
+Skip the note — and apply the `no-release-note` label — for test-only changes,
+docs, CI/workflow plumbing, and pure refactors with no behaviour change.
+
+## Commands
+
+```bash
+pnpm run release:notes:validate
+pnpm run release:notes:github
+pnpm run release:notes:changelog
+pnpm run release:notes:blog
+node tools/release/build-release-notes.mjs --consume
+```
+
+The release version comes from the root `package.json` — bump it first, then
+generate. `--version 0.24.0` overrides it for a dry run before the bump.
+
+Only `--consume` deletes anything; every other mode is a safe dry run.
+
+The release sequence is: bump the version → `release:notes:changelog` →
+`release:notes:blog` → `--consume` → commit → tag → push. The tag build then
+extracts the new `CHANGELOG.md` section into the GitHub release body
+(`tools/release/extract-changelog-section.mjs`) and **fails the release** if
+the section is missing — a tag cut without the changelog step cannot silently
+ship PR-title-only notes.
+
+The website publishes **one post per minor version** (`v0-18` … `v0-22`), and
+release screenshots live under the matching `blog/v0-24/` directory. A patch
+release therefore edits the existing post rather than generating a new one, so
+`--format blog` refuses to overwrite unless you pass `--force`.