changelog-sync

name	changelog-sync
description	Reusable-session release-notes runbook for {{target_repo}}. Finds the range since the last release covered, reads every PR merged in it, groups them by area, writes plain-language notes in the house voice, and opens a PR against {{changelog_path}} only when a new release has actually shipped.

Turn a shipped release of `{{target_repo}}` into changelog notes a reader can follow, without waiting for someone to write them by hand. The schedule re-prompts a persistent session, which reads a ledger to find the last release it covered, pulls every PR merged since then, groups them by area, writes the entry in the changelog's existing voice, and opens one PR per release. Nothing merges without a human, and the agent never edits application code — only `{{changelog_path}}`.

Proactive and schedule-driven; triggered by whatever new tag or release exists since the last checkpoint, whether that's one release or several.

- The `{{cadence}}` schedule fires and a new tag/release may be waiting. - A human asks the agent to draft release notes for a specific tag. - A prior run left the ledger checkpoint stale (e.g. after an incident) and more than one release needs to be covered in this run.

Step 0 — Orient and resume

# Read the durable ledger first — the last release tag covered, and any open
# changelog PR from a prior run.
cat .kortix/memory/changelog-sync-log.md 2>/dev/null || echo "(no ledger yet — first run)"

# Check for an open changelog PR before opening a new one.
gh pr list --repo {{target_repo}} --state open \
  --search 'in:title "release notes" OR label:changelog' \
  --json number,title,headRefName,statusCheckRollup,url

If a prior changelog PR is still open and unreviewed, extend that branch with the newer release instead of opening a second one.

Step 1 — Find the release range

cd /workspace/repo 2>/dev/null || { git clone --filter=blob:none https://github.com/{{target_repo}}.git /workspace/repo && cd /workspace/repo; }
git fetch origin --tags

LAST_TAG=$(grep -m1 '^checkpoint:' .kortix/memory/changelog-sync-log.md | awk '{print $2}')
gh release list --repo {{target_repo}} --limit 10 --json tagName,publishedAt \
  --jq 'sort_by(.publishedAt)'

If $LAST_TAG is empty, this is the first run — seed the checkpoint from the release immediately prior to the newest one (so this run covers exactly the latest release, not the entire history). List every release published after $LAST_TAG, oldest first — cover each one this run, one at a time.

Step 2 — Read the merged PRs for this release

For each release tag $NEW_TAG with predecessor $PREV_TAG:

git log "$PREV_TAG".."$NEW_TAG" --merges --oneline

gh pr list --repo {{target_repo}} --state merged --base main \
  --search "merged:$PREV_TAG_DATE..$NEW_TAG_DATE" \
  --json number,title,body,labels,author,mergedAt,url

For each PR, pull the full description and diff stat, not just the title — the title alone often doesn't say what a user-facing change actually does:

gh pr view <number> --repo {{target_repo}} --json title,body,labels,files

Step 3 — Drop the noise

Exclude PRs carrying any of: internal, chore, ci, dependencies, no-changelog, or whose title starts with chore(deps), ci:, or test:. These are real commits but not something a reader of the changelog cares about. Keep anything user-facing: features, fixes, performance, breaking changes, deprecations.

Step 4 — Group by area and write

Cluster the remaining PRs by the area they touch (read labels first; fall back to the changed paths). Typical groups: Features, Fixes, Performance, Breaking changes. Within each group, write one plain-language line per change — what a user can now do or what stopped being broken, not the internal mechanism. Rephrase every PR title into user-facing language; never paste a raw PR title verbatim.

Read {{changelog_path}}'s existing entries first and match its established format (heading style, date format, grouping labels, tone) rather than inventing a new one.

Step 5 — Isolated branch and PR

cd /workspace/repo
BRANCH="release-notes/$NEW_TAG"
git checkout -b "$BRANCH" origin/main
# edit {{changelog_path}} — insert the new release's entry above the previous one
git add {{changelog_path}}
git commit -m "docs(changelog): release notes for $NEW_TAG"
git push origin "$BRANCH"
gh pr create --repo {{target_repo}} --base main --head "$BRANCH" \
  --title "docs(changelog): release notes for $NEW_TAG" \
  --label changelog \
  --body "Generated by the release-notes agent from PRs merged between
$PREV_TAG and $NEW_TAG. Grouped by area; internal-only PRs and dependency
bumps are dropped. A human reviews the wording and merges."

One PR per release covered. If this run covers more than one release, open them as separate PRs in shipped order rather than combining entries.

Step 6 — Update the ledger

Append a dated entry to .kortix/memory/changelog-sync-log.md (see <ledger-format>) with the new checkpoint tag, then advance it — even if a PR was left open for review rather than merged, the checkpoint still moves to the newest release tag this run covered.

Lives at `.kortix/memory/changelog-sync-log.md`. Every run appends/updates the current entry with: run timestamp, `checkpoint: ` (the newest release tag this run covered — the next run's starting point), the release(s) processed this run, PR link per release (or "not opened — no user-facing PRs in range"), a **PRs dropped as noise** list (number / reason), and **Blockers for next run** (e.g. a release with no merged PRs, or a PR description too thin to summarize without human input). - **No direct push to `main`.** The agent opens a PR and stops. A human merges. - **Changelog-only write surface.** Only `{{changelog_path}}` is ever staged or committed. Application code and past entries (beyond formatting) are read-only context. - **Never publish, tag, or announce.** The agent's output is a pull request. Tagging, publishing the release, and any customer-facing announcement stay with a human, regardless of how confident the draft is. - **Sandbox isolation.** The clone, the PR history read, and the drafting all happen in the session sandbox. Only the changelog branch leaves it. - **Secrets scoped.** The GitHub token is injected at runtime; never written to disk, echoed, or logged. - **One PR per release.** Don't combine multiple releases into a single entry or a single PR; extend an existing open changelog PR rather than duplicating. - **No empty PRs.** If a release has no user-facing PRs after filtering noise, log it in the ledger and don't open a PR for it. - **Checkpoint always advances.** Even a skipped or noise-only release moves the ledger checkpoint forward so the next run doesn't reprocess it.