Release changelog

Create end-user release notes from a base version through the latest commit. Return Markdown unless the user names an output file.

1. Fix the range and format

Read compose_release_notes_interactively in scripts/build_release.sh. Its section names, heading levels, and order are canonical. Read the release/changelog rules in AGENTS.md for the audience and compare footer.

Use the requested base ref. Resolve a bare stable version first; only try its v-prefixed tag when reading a historical release without a bare ref. If no base was given, use git describe --tags --abbrev=0 HEAD and state that choice. The target is HEAD unless the user supplied another commit. Resolve both endpoints with git rev-parse and verify the range with git merge-base --is-ancestor.

Complete when: the exact BASE..TARGET range is valid and the canonical output structure is known from the current repository files.

2. Build an evidence ledger

Inspect every commit with git log --reverse --format=fuller "$BASE..$TARGET" and every net changed file with git diff --name-status "$BASE..$TARGET". Read patches whenever a subject does not prove the user-visible outcome. Classify every commit as either:

• one observable user change, possibly grouped with related commits; or
• excluded because it is only chore, refactor, build, test, ci, or documentation.

Collect issue numbers from commit messages and associated pull requests. Query pull requests with gh pr view ... --json body,closingIssuesReferences and confirm candidates with gh issue view. A printed number must identify a relevant issue, not merely the pull request containing the change. Append verified issues to the matching bullet as (#123, #456). Leave the suffix off when no issue is verified.

Complete when: every commit and changed file is accounted for, every included claim is supported by a diff, and every printed issue number is verified and relevant.

3. Write outcome-first notes

Start directly with the canonical Highlights heading. Put its one- or two-sentence summary on one physical line so extract_highlight_line can consume it.

Emit only non-empty canonical sections, in the script's order and at its exact heading depth. Each section item is one physical line in the form - User-visible outcome so extract_bullets_under_heading can consume it. Describe what users can now do, what changed for them, or what no longer breaks. Use product language rather than commit subjects, implementation symbols, or contributor workflow.

Use the Security section only for user-relevant security changes. Use Known issues only for confirmed unresolved behavior in the target. Combine duplicate outcomes and keep issue suffixes at the end of their bullets.

After a blank line, end with:

**Full changelog:** https://github.com/rokartur/BetterCmdTab/compare/<BASE>...<TARGET-REF>

Use the intended bare release tag as TARGET-REF when the user supplied it; strip a leading v from a new target tag. Otherwise use the resolved target commit SHA.

Complete when: the first line is the canonical Highlights heading, all headings exactly match build_release.sh, empty sections are absent, every bullet is user-facing, and the footer represents the inspected range.