changelog

Required inputs (ask once if missing):

• Starting point: commit SHA, tag, version, or branch — don't proceed without it
• Target file: defaults to CHANGELOG.md at repo root
• Version label (optional): provided → cut a release section; omitted → add to [Unreleased]

Mode from inputs + file state:

• Version label AND [Unreleased] exists → CUT: move [Unreleased] entries to a new [X.Y.Z] section dated today; range entries go to a fresh [Unreleased] (or merge — ask which if both have content).
• Version label, no [Unreleased] → RELEASE: write the new [X.Y.Z] section from the range.
• No version label → UNRELEASED: add to [Unreleased] (create it if missing).
• No file → BOOTSTRAP: create from scratch with the canonical header.

Phase 2 — Triage commits (synthesis, no tool calls)

One logical change = one entry, whatever the commit count. Discard noise: merges, version bumps, lockfile churn, formatting-only, CI tweaks (unless the user asked for full coverage). Buckets — these six only:

• Added — new capability, command, flag, endpoint, config
• Changed — modified behavior of existing functionality
• Deprecated — still works, scheduled for removal
• Removed — gone (breaking; never filed as Changed)
• Fixed — bug fix with a user-observable symptom
• Security — vulnerability fix or hardening (effect, not exploit detail) Material performance changes go under Changed with the word "performance" or numbers; pure internal churn is omitted.

Phase 3 — Verify each entry (parallel across entries)

Diff hunks lie; final-state code does not. Per entry: view_signatures on touched files, view the changed function/type/config as it stands now, structural_search to confirm every name exactly as you'll write it (flag, env var, config key, endpoint path, exported symbol), semantic_search to confirm the behavior matches, graphrag for cross-cutting reach. Versions come from the manifest. Drop anything you cannot verify in user-observable terms.

Phase 4 — Write (one batched edit)

One text_editor/batch_edit call to the target. BOOTSTRAP writes the full canonical structure; other modes touch only the affected section(s) and the link block. Link references (only if git remote get-url origin succeeded; otherwise skip the block — the file stays valid Markdown):

• [unreleased]: <repo>/compare/<latest-tag>...HEAD
• [<new-version>]: <repo>/compare/<prev-tag>...v<new-version>; the first release links its tag: <repo>/releases/tag/v<version>
• Repoint the previous [unreleased] range to the new version.
• Match the host URL shape (GitLab: <repo>/-/compare/a...b, <repo>/-/tags/<tag>) and the repo's tag prefix (v1.2.0 vs 1.2.0).

Phase 5 — Validate

Re-read the file. Confirm every concrete reference in entries (flag, command, path, config key, endpoint, version) via structural_search or manifest, the date is today in YYYY-MM-DD, and ordering is newest-first with canonical bucket order. Mismatch → fix or drop.

After delivery, memorize() project-specific patterns discovered (importance 0.6–0.8).

Entry voice

• Imperative or past tense, consistent within the file (match existing entries).
• One line, ≤140 chars where possible; two lines max when a migration note or scope qualifier is genuinely needed.
• Name the user-facing thing: --no-color flag, WORKER_THREADS env var, /v2/items endpoint — not the internal function.
• Breaking Changed/Removed entries include a one-clause migration cue when the code provides one.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- Entry — one line, specific, names the user-facing thing.

### Changed

- Entry — names the user-facing thing and the behavioral delta.

## [1.2.0] - 2026-05-23

### Fixed

- Entry — describes the user-visible symptom that no longer occurs.

### Security

- Entry — describes what is now prevented; no exploit detail.

[unreleased]: https://github.com/owner/repo/compare/v1.2.0...HEAD
[1.2.0]: https://github.com/owner/repo/compare/v1.1.0...v1.2.0

• Header paragraph preserved verbatim outside BOOTSTRAP.
• [Unreleased] sits on top whenever changes are pending; in CUT it is emptied (or holds the new range entries) after its contents move to the dated section.
• Bucket order: Added, Changed, Deprecated, Removed, Fixed, Security; omit empty buckets.
• Link references follow the file's version order.

Closing line in the conversation (not the file): <mode> · wrote <N> entries to <path> · buckets: <Added=a Changed=c …> · validated <M> references. — <mode> is unreleased, cut <version>, release <version>, or bootstrap.

Empty range → write nothing; reply No changelog-worthy changes in <start>..HEAD. <K> commits scanned.

Stop and ask when:

• The target already has ## [<same-version>] → overwrite, pick another version, or add to [Unreleased]?
• The version label looks non-semver (v2-beta, 2.0) → confirm; semver is MAJOR.MINOR.PATCH[-pre][+build].
• Range refs don't resolve → ask for a valid ref.
• A load-bearing change fits two buckets (e.g. a behavior change that is effectively a removal) → state both and ask.
• An existing CHANGELOG.md uses another format → convert to Keep a Changelog, or write to a different target?

Scope and output

• Write only the target file, in one text_editor or batch_edit call; no scratch outputs.
• Don't rewrite previously-released sections — they are immutable history.
• No commit SHAs, PR refs, author names, or internal file paths in entries; no buckets beyond the six; no empty buckets.
• After writing, one closing line in the conversation. Nothing else.