Maintain consumer-facing release notes / CHANGELOG keyed to forge versions

[misnaej]

Problem

Consumers adopt forge partly by copying text out of forge's docs into their own repo — CI workflow YAML (docs/ci-recipe.md), .githooks/pre-commit customizations, .claude/settings.json hook wiring, etc. When forge changes that text, nothing tells a consumer their pasted copy is now stale.

Live example: PR #29 changed the CI recipe so pytest is invoked with explicit --durations flags (the previous bare-pytest recipe produced an empty slow-tests report in a consumer repo). A consumer who pasted the old recipe has no signal to update it. New CLIs (forge-slow-tests-report), a raised Python floor (>=3.11), new pre-commit steps, and new hooks have the same property.

Goal

A release-note history, keyed to forge version, that a consumer can scan after a forge-upgrade to know what — if anything — they must change in their repo. Emphasis on "consumer action required" items (workflow/recipe/config changes), not just internal refactors.

Why this is tractable in forge specifically

• Releases are already tagged vX.Y.Z; plugin.json rolling-next + /promote mark minor/major boundaries.
• Squash-merge messages on main are already conventional-commit formatted, <=50 words, 3–5 bullets (enforced by forge-pr-squash-comment / pr-manager). That's a clean, pre-curated changelog source — git log <prev-tag>..<tag> on main is already release-note-shaped.

Proposed direction (for the implementing PR, not this issue)

• A CHANGELOG.md (Keep-a-Changelog style) or docs/release-notes.md, one section per released version, with a dedicated "Consumer action required" subsection when a release touches copy-pasted surface (CI recipe, hook config, requires-python, new mandatory step).
• Consider a forge-gen-changelog CLI that derives entries from squash messages between tags (mirrors forge-gen-cli-reference / forge-gen-api-digest), so the changelog stays single-sourced and low-effort — generated, not hand-curated.
• Surface the relevant section after forge-upgrade (it already prints post-upgrade reminders) and link it from the README adoption flow.
• Backfill notable consumer-affecting changes from existing tags (the --durations recipe change, the 3.11 floor, new CLIs/hooks).

Relates to #33 (adoption-docs clarity) — both are about consumer-facing transparency.

[misnaej]

[issue-triage] tier-3-standard applied: consumer-facing CHANGELOG / release notes — high long-term value for adoption transparency, and a natural forge-gen-changelog CLI fits the forge pattern well. Depends on no blocking issue; companion to #33 (adoption docs). Standard priority — consumers are not currently blocked.

[misnaej]

[issue-triage] FOUNDATION §14 (PR #37, merged 2026-06-12) now requires every issue to open with a Requires: line. This issue predates the rule. Dependency scan: standalone feature — no open issue or PR must land first. Please prepend Requires: nothing to the issue body.

[misnaej]

Partial: a hand-authored CHANGELOG.md (main releases v1.16.1 → v1.21.0, minor-only, version-keyed) shipped in #43. Still open: the forge-gen-changelog CLI to derive entries from promotion squash messages between tags (mirroring forge-gen-cli-reference).

[misnaej]

Convention established in #43 — the CHANGELOG.md shipped there uses a per-release ⚠️ Upgrade notes lane (consumer actions: breaking changes, config, new mandatory behavior) above the conventional-commit change groups (Features/Fixes/Refactor/…) that mirror the promotion squash message.

Durable mechanism for this issue's CLI: the upgrade-notes lane can't be auto-generated from per-PR squash messages (they don't carry consumer-impact). Proposal: grow the /promote release summary with an optional ### ⚠️ Upgrade notes block — written once at promotion when context is freshest, human-reviewed — and have forge-gen-changelog lift it verbatim. Keeps single-source-of-truth; the changelog's most valuable lane stays curated, the rest generated.

[misnaej]

Re-scope (audit): the core ask — consumer-action-keyed release notes — is already shipped. CHANGELOG.md is main-only/per-minor with a ⚠️ Upgrade notes lane (the "consumer action required" subsection), and release-process §5 mandates authoring it on dev before promotion. The proposed forge-gen-changelog generator contradicts §5 (the upgrade-notes need human judgment a squash-log can't derive) — drop it. Remaining unmet scope, if pursued: (1) surface the relevant CHANGELOG section after forge-upgrade, (2) backfill older consumer-affecting changes. Both small/optional. [issue-triage]