Release ChangelogCAUTION

The open-source app everyone uses to manage agents at work

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: release-changelog
description: >
  Generate the stable Paperclip release changelog at releases/vYYYY.MDD.P.md by
  reading commits, changesets, and merged PR context since the last stable tag.
---

# Release Changelog Skill

Generate the user-facing changelog for the **stable** Paperclip release.

## Versioning Model

Paperclip uses **calendar versioning (calver)**:

- Stable releases: `YYYY.MDD.P` (e.g. `2026.318.0`)
- Canary releases: `YYYY.MDD.P-canary.N` (e.g. `2026.318.1-canary.0`)
- Git tags: `vYYYY.MDD.P` for stable, `canary/vYYYY.MDD.P-canary.N` for canary

There are no major/minor/patch bumps. The stable version is derived from the
intended release date (UTC) plus the next same-day stable patch slot.

Output:

- `releases/vYYYY.MDD.P.md`
- a `release` Case, upserted by `(caseType, key)` when Cases are enabled, with a
  `body` document revision containing the changelog body

Important rules:

- even if there are canary releases such as `2026.318.1-canary.0`, the changelog file stays `releases/v2026.318.1.md`
- do not derive versions from semver bump types
- do not create canary changelog files

## Channel Process — Source Commit and File Location

Stables promote a **soaked beta**, so the changelog describes the beta's
source commit, not the tip of `master`:

- The release **source** is the commit the newest `beta/v<beta-version>`
  tag points at (`{beta-src}` below). Resolve it with:

  ```bash
  git fetch origin --tags
  npm view paperclipai dist-tags   # the beta dist-tag names the version
  git rev-parse 'beta/v{beta-version}^{commit}'
  ```

- Commits on `master` after `{beta-src}` ship in the **next** release.
  Never include them; they are input for a "what's next" section, not the
  changelog.
- During the soak, the file lives at `releases/beta/v{beta-version}.md`
  on the branch `release-notes/v{beta-version}` (PR to `master`). The
  release workflow pushes that branch with a generated skeleton when the
  beta publishes; work on it and rewrite the skeleton in place. If the
  branch does not exist (a beta cut before the automation), create it
  from `origin/master` and seed the skeleton:

  ```bash
  ./scripts/draft-stable-notes.sh {beta-version}
  ```

- The PR must merge to `master` **before** the stable is dispatched: the
  stable preflight reads the file from `master` and fails without it.
- Never create `releases/vYYYY.MDD.P.md` yourself on this path — after
  the stable ships, the workflow opens a canonicalization PR that renames
  the beta-keyed file to it.
- **Fix path exception** (patch releases from a `candidate/release-*`
  branch): there the notes *do* go directly on the candidate branch as
  `releases/vYYYY.MDD.P.md`, committed alongside the cherry-picked fixes.

## Step 0 — Idempotency Check

Before generating anything, check whether the changelog already exists:

```bash
ls releases/beta/v{beta-version}.md 2>/dev/null   # soak-window home
ls releases/vYYYY.MDD.P.md 2>/dev/null            # canonicalized / fix path
git ls-remote origin 'refs/heads/release-notes/v{beta-version}'
```

A `release-notes/v{beta-version}` branch holding only the generated
skeleton is the normal starting state, not a conflict — rewrite it in
place.

If it exists:

1. read it first
2. present it to the reviewer
3. ask whether to keep it, regenerate it, or update specific sections
4. never overwrite it silently

## Step 1 — Determine the Stable Range

Find the last stable tag and the beta source commit:

```bash
git tag --list 'v*' --sort=-version:refname | head -1
beta_src="$(git rev-parse 'beta/v{beta-version}^{commit}')"
git log v{last}..${beta_src} --oneline --no-merges
```

The changelog range is always `v{last}..{beta-src}` — never `..HEAD` and
never `..origin/master`.

The stable version comes from one of:

- an explicit maintainer request
- `./scripts/release.sh stable --date YYYY-MM-DD --print-version`
- the release plan already agreed in `doc/RELEASING.md`

Do not derive the changelog version from a canary tag or prerelease suffix.
Do not derive major/minor/patch bumps from API intent — calver uses the date and same-day stable slot.

## Step 2 — Gather the Raw Inputs

Collect release data from:

1. git commits since the last stable tag
2. `.changeset/*.md` files
3. merged PRs via `gh` when available

Useful commands:

```bash
git log v{last}..{beta-src} --oneline --no-merges
git log v{last}..{beta-src} --format="%H %s" --no-merges
ls .changeset/*.md | grep -v README.md
gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels
```

## Step 3 — Detect Breaking Changes

Look for:

- destructive migrations
- removed or changed API fields/endpoints
- renamed or removed config keys
- `BREAKING:` or `BREAKING CHANGE:` commit signals

Key commands:

```bash
git diff --name-only v{last}..{beta-src} -- packages/db/src/migrations/
git diff v{last}..{beta-src} -- packages/db/src/schema/
git diff v{last}..{beta-src} -- server/src/routes/ server/src/api/
git log v{last}..{beta-src} --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
```

If breaking changes are detected, flag them prominently — they must appear in the
Breaking Changes section with an upgrade path.

## Step 4 — Categorize for Users

Use these stable changelog sections:

- `Breaking Changes`
- `Highlights`
- `Improvements`
- `Fixes`
- `Upgrade Guide` when needed

Exclude purely internal refactors, CI changes, and docs-only work unless they materially affect users.

Guidelines:

- group related commits into one user-facing entry
- write from the user perspective
- keep highlights short and concrete
- spell out upgrade actions for breaking changes
- **write at full stable depth from the first pass**: the beta-keyed
  draft ships verbatim as the stable's notes, so the previous stable's
  file is the density bar the moment the draft is first written — never
  leave it at generated-skeleton density for the soak. The skeleton's
  nested PR summaries are raw material t

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

.claude/skills/company-creator

.claude/skills/paperclip

Gates applied: no_behavioural_pass.