From 6d60731c66adfa63588f0e0b4cded7f52662aec9 Mon Sep 17 00:00:00 2001
From: Chris Barth <chrisjbarth@hotmail.com>
Date: Wed, 16 Sep 2026 07:29:57 -0500
Subject: [PATCH 1/3] Build pull request changelogs from release membership

The prs data source compared adjacent tags reachable from the current
branch, so what a section contained depended on where it was generated
from, and commits without a pull request were dropped in silence. A
repository with more than one release line, such as a 6.x branch beside
master, lost whole sections.

A release now contains the commits reachable from its tag but not from
any tag of a lower version, read from the local clone. Each commit
belongs to the lowest release that contains it, so a section comes out
the same on every branch, and sections are ordered by semver.

Three options go with it:

  pullRequestRepos  other repositories to look for pull requests in,
                    such as an upstream, a fork, or where the project
                    used to live
  commitNotes       what to say about a commit with no pull request, or
                    which pull request a cherry-pick came from
  frozenBefore      keep the sections of older releases as they are

A commit that matches neither a pull request nor a commitNotes entry is
reported with an entry to paste into the configuration, rather than
disappearing from the changelog.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 README.md                     |  95 +++-
 lib/_options.js               |  15 +
 lib/src/Gren.js               | 943 ++++++++++++++++++++++++++++++----
 lib/src/_git.js               | 147 ++++++
 package-lock.json             |   9 +-
 package.json                  |   2 +-
 test/Gren.membership.spec.js  | 678 ++++++++++++++++++++++++
 test/_git.spec.js             | 119 +++++
 test/fixtures/release-repo.js |  94 ++++
 9 files changed, 1998 insertions(+), 104 deletions(-)
 create mode 100644 lib/src/_git.js
 create mode 100644 test/Gren.membership.spec.js
 create mode 100644 test/_git.spec.js
 create mode 100644 test/fixtures/release-repo.js

diff --git a/README.md b/README.md
index 707c0b52..aff69ceb 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ Since this package was forked, many changes have been made to support my particu
 - Because not all commits you need to track changes of have PRs (security vulnerabilities), there is an `overridePrs` config value for which you can specify PRs to be included.
   - It should return a function that returns a list of PRs.
   - It will be passed the current list of PRs.
+  - For most cases, [`commitNotes`](#commits-without-a-pull-request) describes those changes without code.
 
 ## OK, what can `gren` do for me?
 
@@ -72,7 +73,7 @@ _(yes, this is one of_ 🤖 _'s actual releases)_
 
 ## Feed `gren` 🤖
 
-Where is the data coming from? There are two options:
+Where is the data coming from? There are three main options:
 
 ### `issues` (⭐)
 
@@ -123,6 +124,88 @@ In order to have splendidly generated release notes, we recommend to follow thes
 6. Wrap the body at 72 characters
 7. Use the body to explain _what_ and _why_ not _how_
 
+### `prs`
+
+With `--data-source=prs` (or `prs-with-issues`), `gren` lists the merged pull requests in each release.
+
+#### Which pull requests are in a release
+
+A release contains the commits reachable from its tag but not from any tag with a lower version.
+Each commit belongs to the lowest release that contains it, so every release's section is the same whichever branch you run `gren` on.
+This works across release lines. For example, with 7.x on `master` and 6.x on a `6.x` branch:
+
+- 6.2.0 can be cut from `master`, or from `6.x` after merging `master` into it. The merge brings `master`'s pull requests into 6.2.0.
+- 7.0.0 then leaves out what 6.2.0 already released.
+- A 6.2.1 made after 7.0.0 lists only its own pull requests, and appears in the changelog on both branches.
+
+Merge one release line into another with a merge commit. A squash merge hides the commits, and their pull requests, that it brings in.
+
+The version being prepared (from `package.json`) gets a section for the commits on `--head` that no tag contains yet.
+
+Without `--tags`, `gren` writes that section and the latest tag `--head` contains, so on a maintenance branch it works on that line's latest release rather than on the highest version in the repository.
+`--tags=<new-tag>..<old-tag>` puts everything since the old tag in the new tag's section, taking in the releases between them.
+
+`gren` reads commits from your local clone, so fetch the tags first, e.g. `git fetch upstream --tags`.
+It stops if a tag on GitHub is missing locally or points elsewhere.
+It needs the whole history too, so run `git fetch --unshallow` in a shallow clone, and check out with `fetch-depth: 0` in GitHub Actions.
+
+#### Matching commits to pull requests
+
+A commit matches a pull request whose merge commit it is.
+The commits a merge-commit pull request brings in are covered by that pull request.
+Any other commit is looked up on GitHub, which finds rebase merges.
+
+If the project's older pull requests are in another repository, such as an upstream, a fork or where the project used to live, list it in `pullRequestRepos`:
+
+```js
+pullRequestRepos: ["node-saml/passport-saml"],
+```
+
+A cherry-pick is a new commit, so it belongs to the release that contains it and matches the pull request that merged the cherry-pick, if it had one.
+The pull request it was taken from keeps its own entry in its own release, as both releases really do contain the change.
+A cherry-pick pushed straight to a branch matches nothing, and is reported like any other commit without a pull request.
+
+#### Commits without a pull request
+
+Commits that no pull request describes, such as a security fix or a direct push, are not added to the changelog.
+`gren` prints them after generating, with entries you can copy into `commitNotes` in your [configuration file](#configuration-file):
+
+```js
+commitNotes: {
+  "8ac6118f3a": {
+    title: "Fix a signature wrapping vulnerability",
+    labels: ["security"],
+    url: "https://github.com/OWNER/REPO/security/advisories/GHSA-xxxx-xxxx-xxxx",
+    text: "GHSA-xxxx-xxxx-xxxx",
+    author: "reporter-login",
+  },
+  "ec309ec36b": {
+    pr: 330,
+  },
+},
+```
+
+Keys are commit SHAs of at least 7 characters. Every field is optional.
+An entry is placed in the release that contains its commit and grouped by its labels like a pull request.
+If the commit is a pull request's merge commit, the entry's fields replace that pull request's.
+
+`pr` points at a pull request, as `330`, `"#330"` or `"owner/repo#330"`, and the entry takes its title, labels, author and link from it.
+Use it for a cherry-pick that was pushed without a pull request of its own: the change is listed under the pull request it came from, in the release the cherry-pick landed in, and editing that pull request's title or labels still changes both releases' sections.
+If the same pull request is already in that release, the two are listed once.
+To stop a commit being reported, match it with `ignoreCommitsWith`, e.g. `["^Release \\d"]`.
+
+To fix a section, edit the pull request's title or labels, or `commitNotes`, and generate the changelog again.
+
+#### Keeping older sections
+
+Rebuilding every section can change sections you have reviewed, and early history may not have pull requests at all.
+`--frozen-before` (`frozenBefore` in the configuration file) takes a date, a tag or a commit SHA.
+Releases made before it are copied from the existing changelog as they are, matched by the version in each section's first line; newer releases are generated.
+
+```shell
+gren changelog --generate --override --data-source=prs --frozen-before=v6.0.0
+```
+
 ## Installation
 
 `gren` requires **Node.js 24 or newer** (the current LTS).
@@ -269,6 +352,7 @@ Every option can be passed on the command line, or set in a [configuration file]
 | `-g, --group-by`            | `<label>`                                             | Group the issues using the labels as group headings. You can set custom headings for groups of labels from a configuration file.                                                                     |                        |
 | `-L, --ignore-labels`       | `<label1>,<label2>`                                   | Ignore the specified labels.                                                                                                                                                                         |                        |
 | `-I, --ignore-issues-with`  | `<label1>,<label2>`                                   | Ignore issues that contains one of the specified labels.                                                                                                                                             |                        |
+| `-R, --pull-request-repos`  | `<owner/repo1>,<owner/repo2>`                         | Other repositories to look for pull requests in, such as an upstream, a fork or where the project used to live. Only used when --data-source is prs or prs-with-issues.                              |                        |
 | `-M, --milestone-match`     | `<prefix>`                                            | The title that the script needs to match to link the release to the milestone. e.g. v will match v0.1.0 [Release {{tag_name}}]                                                                       | `Release {{tag_name}}` |
 | `-m, --only-milestones`     |                                                       | Add to the release bodies only the issues that have a milestone                                                                                                                                      |                        |
 | `-q, --quiet`               |                                                       | Run command without console logs.                                                                                                                                                                    |                        |
@@ -283,10 +367,11 @@ Every option can be passed on the command line, or set in a [configuration file]
 
 ### Changelog options
 
-| Option                     | Value           | Description                                                          | Default        |
-| -------------------------- | --------------- | -------------------------------------------------------------------- | -------------- |
-| `-G, --generate`           |                 | Generate the changelog with gren rather than using the repo releases |                |
-| `-f, --changelog-filename` | `<filename.md>` | The name of the changelog file. [CHANGELOG.md]                       | `CHANGELOG.md` |
+| Option                     | Value              | Description                                                                                                                                                                                                               | Default        |
+| -------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `-G, --generate`           |                    | Generate the changelog with gren rather than using the repo releases                                                                                                                                                      |                |
+| `-f, --changelog-filename` | `<filename.md>`    | The name of the changelog file. [CHANGELOG.md]                                                                                                                                                                            | `CHANGELOG.md` |
+| `-F, --frozen-before`      | `<date\|tag\|sha>` | Copy the sections of releases made before this date, or before this tag's or commit's date, from the existing changelog instead of generating them. Only used with --generate and the prs or prs-with-issues data source. |                |
 
 <!-- GREN-OPTIONS:END -->
 
diff --git a/lib/_options.js b/lib/_options.js
index 4e71f44e..a659ca51 100644
--- a/lib/_options.js
+++ b/lib/_options.js
@@ -18,6 +18,13 @@ export const changelogOptions = [
     description: "The name of the changelog file. [CHANGELOG.md]",
     defaultValue: "CHANGELOG.md",
   },
+  {
+    short: "-F",
+    name: "frozen-before",
+    valueType: "<date|tag|sha>",
+    description:
+      "Copy the sections of releases made before this date, or before this tag's or commit's date, from the existing changelog instead of generating them. Only used with --generate and the prs or prs-with-issues data source.",
+  },
   {
     short: false,
     name: false,
@@ -141,6 +148,14 @@ export const globalOptions = [
     description: "Ignore issues that contains one of the specified labels.",
     action: (value) => value.split(","),
   },
+  {
+    short: "-R",
+    name: "pull-request-repos",
+    valueType: "<owner/repo1>,<owner/repo2>",
+    description:
+      "Other repositories to look for pull requests in, such as an upstream, a fork or where the project used to live. Only used when --data-source is prs or prs-with-issues.",
+    action: (value) => value.split(","),
+  },
   {
     short: "-M",
     name: "milestone-match",
diff --git a/lib/src/Gren.js b/lib/src/Gren.js
index 8bd8b90f..27b7f44c 100644
--- a/lib/src/Gren.js
+++ b/lib/src/Gren.js
@@ -5,9 +5,10 @@ import { generate } from "./_template.js";
 import connectivity from "connectivity";
 import templateConfig from "./templates.js";
 import ObjectAssign from "object-assign-deep";
-import cmp from "semver-compare";
+import semver from "semver";
 import fs from "node:fs";
 import { execSync } from "node:child_process";
+import * as git from "./_git.js";
 
 const defaults = {
   tags: [],
@@ -23,11 +24,47 @@ const defaults = {
   ignoreCommitsWith: false,
   groupBy: false,
   milestoneMatch: "Release {{tag_name}}",
+  pullRequestRepos: [],
+  commitNotes: {},
+  frozenBefore: false,
 };
 
 const MAX_TAGS_LIMIT = 99;
 const TAGS_LIMIT = 30;
 
+// The data sources whose releases are built from the commits each release contains.
+const MEMBERSHIP_DATA_SOURCES = ["prs", "prs-with-issues"];
+
+/**
+ * Get the semver version a tag or release name stands for
+ *
+ * @param  {string} name e.g. v1.2.3 or 1.2.3
+ *
+ * @return {string|null} The version, or null when the name is not semver
+ */
+function parseVersion(name) {
+  return (typeof name === "string" && semver.valid(name.replace(/^v/, ""))) || null;
+}
+
+/**
+ * Compare two tag or release names by semver. Names that are not semver sort below those that are.
+ *
+ * @param  {string} a
+ * @param  {string} b
+ *
+ * @return {number}
+ */
+function compareVersions(a, b) {
+  const versionA = parseVersion(a);
+  const versionB = parseVersion(b);
+
+  if (versionA && versionB) {
+    return semver.compare(versionA, versionB);
+  }
+
+  return Boolean(versionA) - Boolean(versionB);
+}
+
 /** Class creating release notes and changelog notes */
 class Gren {
   constructor(props = {}) {
@@ -47,14 +84,18 @@ class Gren {
       ignoreTagsWith,
     } = this.options;
 
-    this.options.head =
-      this.options.head || execSync("git symbolic-ref --short HEAD", { encoding: "utf-8" });
-    try {
-      execSync("git rev-parse --abbrev-ref --symbolic-full-name @{u}");
-    } catch {
-      this.options.head = execSync("git remote show origin | grep 'HEAD branch' | cut -d' ' -f5", {
-        encoding: "utf-8",
-      });
+    // A head passed in is used as given. Otherwise use the current branch, or the remote's
+    // default branch when the current one has no upstream.
+    if (!this.options.head) {
+      this.options.head = execSync("git symbolic-ref --short HEAD", { encoding: "utf-8" });
+      try {
+        execSync("git rev-parse --abbrev-ref --symbolic-full-name @{u}", { stdio: "ignore" });
+      } catch {
+        this.options.head = execSync(
+          "git remote show origin | grep 'HEAD branch' | cut -d' ' -f5",
+          { encoding: "utf-8" },
+        );
+      }
     }
     this.options.head = this.options.head.trim();
     this.options.tags = utils.convertStringToArray(tags);
@@ -62,6 +103,8 @@ class Gren {
     this.options.ignoreIssuesWith = utils.convertStringToArray(ignoreIssuesWith);
     this.options.ignoreCommitsWith = utils.convertStringToArray(ignoreCommitsWith);
     this.options.ignoreTagsWith = utils.convertStringToArray(ignoreTagsWith);
+    this.options.pullRequestRepos = this._parseRepos(this.options.pullRequestRepos);
+    this.options.commitNotes = this._validateCommitNotes(this.options.commitNotes);
     this.options.version = this.options.version || utils.findRelevantVersion();
 
     if (limit && limit > 0 && limit <= MAX_TAGS_LIMIT) {
@@ -98,6 +141,94 @@ class Gren {
     });
 
     this.repoParams = { owner: username, repo };
+    this.commitPullRequests = new Map();
+    this.notePullRequests = new Map();
+    this.overriddenPullRequests = new Map();
+  }
+
+  /**
+   * Parse the repos to look for pull requests in, besides the current one
+   *
+   * @private
+   *
+   * @param  {Array|string} repos e.g. ["owner/repo"] or "owner/repo,owner/other"
+   *
+   * @return {Object[]} The repos as { owner, repo }
+   */
+  _parseRepos(repos) {
+    const names = Array.isArray(repos) ? repos : String(repos || "").split(",");
+
+    return names
+      .map((name) => String(name).trim())
+      .filter(Boolean)
+      .map((fullName) => {
+        const [owner, repo, ...rest] = fullName.split("/");
+
+        if (!owner || !repo || rest.length) {
+          throw chalk.red(`pullRequestRepos entries must look like "owner/repo": ${fullName}`);
+        }
+
+        return { owner, repo };
+      });
+  }
+
+  /**
+   * Parse the pull request a commitNotes entry points to
+   *
+   * @private
+   *
+   * @param  {number|string} reference e.g. 330, "#330" or "owner/repo#330"
+   *
+   * @return {Object|undefined} The pull request as { owner, repo, pull_number }, without the
+   *                            repo when the reference names none
+   */
+  _parseNotePullRequest(reference) {
+    const parts = /^(?:([^/\s]+)\/([^/#\s]+))?#?([1-9]\d*)$/.exec(String(reference).trim());
+
+    if (!parts) {
+      return undefined;
+    }
+
+    const [, owner, repo, number] = parts;
+
+    return { ...(owner ? { owner, repo } : {}), pull_number: Number(number) };
+  }
+
+  /**
+   * Check the commitNotes option maps commit SHAs to entries
+   *
+   * @private
+   *
+   * @param  {Object} commitNotes
+   *
+   * @return {Object}
+   */
+  _validateCommitNotes(commitNotes) {
+    if (!commitNotes) {
+      return {};
+    }
+
+    if (typeof commitNotes !== "object" || Array.isArray(commitNotes)) {
+      throw chalk.red("commitNotes must be an object that maps commit SHAs to entries");
+    }
+
+    Object.entries(commitNotes).forEach(([sha, note]) => {
+      if (!/^[0-9a-f]{7,40}$/i.test(sha)) {
+        throw chalk.red(`commitNotes keys must be commit SHAs of at least 7 characters: ${sha}`);
+      }
+
+      if (!note || typeof note !== "object" || Array.isArray(note)) {
+        throw chalk.red(`The commitNotes entry for ${sha} must be an object`);
+      }
+
+      if (note.pr !== undefined && !this._parseNotePullRequest(note.pr)) {
+        throw chalk.red(
+          `The commitNotes entry for ${sha} must give pr as a number, "#123" or "owner/repo#123"`,
+        );
+      }
+    });
+
+    return commitNotes;
   }
 
   /**
@@ -134,8 +265,13 @@ class Gren {
     await this._hasNetwork();
     this._checkChangelogFile();
 
+    // Read before the file is replaced, so frozen sections can be carried over.
+    const existingSections =
+      this.options.generate && this.options.frozenBefore
+        ? this._readChangelogSections()
+        : undefined;
     const releases = this.options.generate
-      ? await this._getReleaseBlocks()
+      ? await this._getReleaseBlocks(existingSections)
       : await this._getListReleases();
 
     if (releases.length === 0) {
@@ -184,6 +320,64 @@ class Gren {
     loaded(chalk.green(`Changelog created in ${filePath}`));
   }
 
+  /**
+   * Split the existing changelog file into its release sections
+   *
+   * A section is keyed by the version in its first line. A section without a version, such
+   * as "## 3.x", stays attached to the section before it.
+   *
+   * @private
+   *
+   * @return {Map<string, string>} Version to the section's text, exactly as in the file
+   */
+  _readChangelogSections() {
+    const filePath = process.cwd() + "/" + this.options.changelogFilename;
+    const sections = new Map();
+
+    if (!fs.existsSync(filePath)) {
+      return sections;
+    }
+
+    const { changelogTitle, releaseSeparator } = this.options.template;
+    let content = fs.readFileSync(filePath, "utf-8");
+
+    if (content.startsWith(changelogTitle)) {
+      content = content.slice(changelogTitle.length);
+    }
+
+    let current = null;
+    // A changelog written with nothing between its releases can only be split on the headings,
+    // at the start of each one so that the release before it keeps its last line.
+    const chunks = releaseSeparator
+      ? content.split(releaseSeparator)
+      : content.split(/(?<=\n)(?=#{1,6} +v?\d+\.\d+\.\d+)/);
+
+    chunks.forEach((chunk) => {
+      const heading = chunk.trimStart().split("\n")[0];
+      const match = heading.match(/v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+      const version = match && parseVersion(match[1]);
+
+      if (version && !sections.has(version)) {
+        current = version;
+        sections.set(version, chunk);
+      } else if (current) {
+        sections.set(current, sections.get(current) + releaseSeparator + chunk);
+      }
+    });
+
+    // Without the existing sections every frozen release would be dropped from the file that is
+    // about to be written over it.
+    if (!sections.size && content.trim()) {
+      throw chalk.red(
+        `\nNo releases could be read from ${this.options.changelogFilename}, so the sections ` +
+          "frozenBefore keeps cannot be found. Check that the release and releaseSeparator " +
+          "templates match the file.",
+      );
+    }
+
+    return sections;
+  }
+
   /**
    * Edit a release from a given tag (in the options)
    *
@@ -465,47 +659,58 @@ class Gren {
   }
 
   /**
-   * Get the merged pull requests from the repo
+   * Get the merged pull requests from a repo
    *
    * @private
    *
-   * @param {number} page
-   * @param {number} limit
+   * @param {string} since Stop paging once pull requests were last updated before this date
+   * @param {Object} repoParams The repo as { owner, repo }
    *
-   * @return {Promise[]}     The promises which returns pull requests
+   * @return {Promise<Object[]>} The pull requests
    */
-  async _getMergedPullRequests(since, page = 1, limit = 1000) {
-    const results = await this.octokit.rest.pulls.list({
-      ...this.repoParams,
-      state: "closed",
-      sort: "updated",
-      direction: "desc",
-      per_page: limit,
-      page,
-    });
+  async _getMergedPullRequests(since, repoParams = this.repoParams) {
+    const prs = [];
+
+    for (let page = 1; ; page++) {
+      const {
+        headers: { link },
+        data,
+      } = await this.octokit.rest.pulls.list({
+        ...repoParams,
+        state: "closed",
+        sort: "updated",
+        direction: "desc",
+        per_page: 100,
+        page,
+      });
+      const totalPages = this._getLastPage(link);
 
-    const {
-      headers: { link },
-      data: prs,
-    } = results;
-    const totalPages = this._getLastPage(link);
-    const filterPrs = prs.filter((pr) => pr.merged_at);
-    if (
-      prs.length > 0 &&
-      new Date(since) < new Date(prs[prs.length - 1].updated_at) &&
-      totalPages &&
-      +page < totalPages
-    ) {
-      return this._getMergedPullRequests(since, page + 1).then((prsResults) =>
-        prsResults.concat(filterPrs),
-      );
+      prs.push(...data);
+
+      if (
+        !data.length ||
+        !totalPages ||
+        page >= totalPages ||
+        new Date(since) >= new Date(data[data.length - 1].updated_at)
+      ) {
+        break;
+      }
     }
 
     if (typeof this.options.overridePrs === "function") {
-      return this.options.overridePrs(prs);
+      const overridden = this.options.overridePrs(prs);
+      const byUrl = new Map(overridden.map((pr) => [pr.html_url, pr]));
+
+      // Commit lookups get pull requests as GitHub has them, so keep what overridePrs made of
+      // each one, including the ones it left out, to apply it to those as well.
+      prs.forEach(({ html_url: url }) => {
+        this.overriddenPullRequests.set(url, byUrl.get(url) || null);
+      });
+
+      return overridden;
     }
 
-    return filterPrs;
+    return prs.filter((pr) => pr.merged_at);
   }
 
   /**
@@ -568,15 +773,18 @@ class Gren {
     const { template } = this.options;
 
     return releases
-      .map((release) =>
-        generate(
-          {
-            release: release.name || release.tag_name,
-            date: utils.formatDate(new Date(release.published_at)),
-            body: release.body,
-          },
-          template.release,
-        ),
+      .map(
+        (release) =>
+          // Frozen sections are copied from the existing file as they are.
+          release.verbatim ??
+          generate(
+            {
+              release: release.name || release.tag_name,
+              date: utils.formatDate(new Date(release.published_at)),
+              body: release.body,
+            },
+            template.release,
+          ),
       )
       .join(template.releaseSeparator);
   }
@@ -659,7 +867,8 @@ class Gren {
       {
         labels: this._templateLabels(issue),
         name: issue.title,
-        text: "#" + issue.number,
+        // commitNotes entries can set their own text, e.g. an advisory ID.
+        text: issue.text ?? "#" + issue.number,
         url: issue.html_url,
         body: issue.body,
         pr_base: issue.base && issue.base.ref,
@@ -1016,25 +1225,314 @@ class Gren {
   }
 
   /**
-   * Filter the pull requests in case the release is milestone,
-   * or otherwise by dates range.
+   * Find the pull requests and commitNotes entries for the commits of each release
+   *
+   * A commit matches a pull request whose merge commit it is, in the current repo or one of
+   * the pullRequestRepos. Commits a merge-commit pull request brought in are covered by that
+   * pull request. Other commits are looked up one at a time, which finds rebase merges.
    *
    * @private
    *
-   * @param  {Array} range The release ranges
-   * @param  {Object} pullRequest GitHub pull request
+   * @param  {Array} releaseRanges Ranges whose third item is the release's commits
    *
-   * @return {Boolean}
+   * @return {Promise<Object>} { lists, unmatched }, where lists holds each release's pull
+   * requests, newest first, and unmatched the commits nothing describes
    */
-  _filterBlockPullRequest(range, pullRequest) {
-    if (this.options.dataSource === "milestones") {
-      return (
-        this.options.milestoneMatch.replace("{{tag_name}}", range[0].name) ===
-        pullRequest.milestone.title
+  async _getReleasePullRequests(releaseRanges) {
+    const repos = [this.repoParams, ...this.options.pullRequestRepos];
+    const commits = releaseRanges.flatMap((range) => range[2]);
+    const byMergeCommit = new Map();
+    // Branches other pull requests merge into, such as master or 6.x.
+    const baseBranches = new Set();
+
+    if (commits.length) {
+      // A pull request is last updated no earlier than its merge commit was made.
+      const since = new Date(
+        commits.reduce((oldest, { date }) => Math.min(oldest, Date.parse(date)), Infinity),
+      ).toISOString();
+
+      for (const repoParams of repos) {
+        const prs = await this._getMergedPullRequests(since, repoParams);
+
+        prs.forEach((pr) => {
+          if (pr.merge_commit_sha && !byMergeCommit.has(pr.merge_commit_sha)) {
+            byMergeCommit.set(pr.merge_commit_sha, pr);
+          }
+
+          if (pr.base?.repo) {
+            baseBranches.add(`${pr.base.repo.full_name}:${pr.base.ref}`);
+          }
+        });
+      }
+    }
+
+    // A pull request from a base branch, such as master into 6.x, syncs release lines. The
+    // commits it brings in keep their own pull requests, and those without one are reported.
+    const isBranchSync = (pr) =>
+      Boolean(pr.head?.repo) && baseBranches.has(`${pr.head.repo.full_name}:${pr.head.ref}`);
+    const covered = new Set(
+      commits
+        .filter(({ sha, parents }) => {
+          const pr = byMergeCommit.get(sha);
+
+          return parents.length > 1 && pr && !isBranchSync(pr);
+        })
+        .flatMap(({ sha }) => git.mergeBranchCommits(sha)),
+    );
+    const unmatched = [];
+    const lists = [];
+
+    for (const range of releaseRanges) {
+      const found = new Map();
+      const noted = new Set();
+
+      for (const commit of range[2]) {
+        const note = this._findCommitNote(commit.sha);
+        let pr = byMergeCommit.get(commit.sha);
+
+        if (!pr && !note && !covered.has(commit.sha) && !this._isIgnoredCommit(commit)) {
+          pr = await this._getCommitPullRequest(commit.sha, repos, isBranchSync);
+
+          if (pr && this.overriddenPullRequests.has(pr.html_url)) {
+            pr = this.overriddenPullRequests.get(pr.html_url) || undefined;
+          }
+
+          if (!pr) {
+            unmatched.push({ release: range[0].name, commit });
+          }
+        }
+
+        // A commitNotes entry can point at the pull request the commit came from, such as the
+        // one a cherry-pick was taken from, so its title and labels stay with the pull request.
+        const notePr = note?.pr === undefined ? undefined : await this._getNotePullRequest(note.pr);
+        const item = note ? this._applyCommitNote(note, commit, notePr ?? pr) : pr;
+
+        // Every commit of a rebase-merged pull request matches that pull request, so entries are
+        // keyed by the pull request rather than by a commitNotes url, which would leave two
+        // entries for the one pull request. The newest commit with a note wins, as commits are
+        // newest first.
+        const key = item && ((notePr ?? pr)?.html_url ?? item.html_url ?? commit.sha);
+
+        if (item && !noted.has(key)) {
+          // A pull request a commitNotes entry points to was merged elsewhere, so the commit is
+          // when its change reached this release.
+          const sortDate = (notePr ? commit.date : item.merged_at) || commit.date;
+
+          found.set(key, { ...item, sortDate });
+
+          if (note) {
+            noted.add(key);
+          }
+        }
+      }
+
+      lists.push(
+        Array.from(found.values())
+          .filter(this._filterPullRequest.bind(this))
+          .sort((pr1, pr2) => Date.parse(pr2.sortDate) - Date.parse(pr1.sortDate)),
       );
     }
 
-    return range[2].some((commit) => pullRequest.merge_commit_sha === commit.sha);
+    return { lists, unmatched };
+  }
+
+  /**
+   * Look up the merged pull request that introduced a commit, in each repo in turn
+   *
+   * @private
+   *
+   * @param  {string} sha
+   * @param  {Object[]} repos The repos as { owner, repo }
+   * @param  {Function} isBranchSync Whether a pull request only syncs one release line into
+   *                                 another, in which case the search carries on
+   *
+   * @return {Promise<Object|undefined>}
+   */
+  async _getCommitPullRequest(sha, repos, isBranchSync) {
+    if (!this.commitPullRequests.has(sha)) {
+      let found;
+
+      for (const repoParams of repos) {
+        try {
+          const { data } = await this.octokit.rest.repos.listPullRequestsAssociatedWithCommit({
+            ...repoParams,
+            commit_sha: sha,
+          });
+
+          found = data.find((pr) => pr.merged_at && !isBranchSync(pr));
+        } catch (error) {
+          // A 422 means the commit is not in this repo, which is the usual answer for a repo in
+          // pullRequestRepos. Anything else, including a 404 for a repo that is not there at
+          // all, would quietly leave pull requests out of the release notes.
+          if (error.status !== 422) {
+            throw chalk.red(
+              `\nCould not look up the pull request for ${sha} in ${repoParams.owner}/${repoParams.repo}: ${error.message}`,
+            );
+          }
+        }
+
+        if (found) {
+          break;
+        }
+      }
+
+      this.commitPullRequests.set(sha, found);
+    }
+
+    return this.commitPullRequests.get(sha);
+  }
+
+  /**
+   * Get the pull request a commitNotes entry points to
+   *
+   * @private
+   *
+   * @param  {number|string} reference e.g. 330, "#330" or "owner/repo#330"
+   *
+   * @return {Promise<Object>}
+   */
+  async _getNotePullRequest(reference) {
+    const key = String(reference).trim();
+
+    if (!this.notePullRequests.has(key)) {
+      const { owner, repo, pull_number } = {
+        ...this.repoParams,
+        ...this._parseNotePullRequest(reference),
+      };
+
+      try {
+        const { data } = await this.octokit.rest.pulls.get({ owner, repo, pull_number });
+
+        this.notePullRequests.set(key, data);
+      } catch (error) {
+        throw chalk.red(
+          `\nCould not get ${owner}/${repo}#${pull_number}, which a commitNotes entry points to: ${error.message}`,
+        );
+      }
+    }
+
+    return this.notePullRequests.get(key);
+  }
+
+  /**
+   * Find the commitNotes entry for a commit
+   *
+   * @private
+   *
+   * @param  {string} sha
+   *
+   * @return {Object|undefined}
+   */
+  _findCommitNote(sha) {
+    const { commitNotes } = this.options;
+    const key = Object.keys(commitNotes).find((prefix) => sha.startsWith(prefix.toLowerCase()));
+
+    return key && commitNotes[key];
+  }
+
+  /**
+   * Check whether a commit matches ignoreCommitsWith
+   *
+   * @private
+   *
+   * @param  {Object} commit
+   *
+   * @return {boolean}
+   */
+  _isIgnoredCommit({ subject }) {
+    return this.options.ignoreCommitsWith.some((pattern) => new RegExp(pattern, "i").test(subject));
+  }
+
+  /**
+   * Turn a commitNotes entry into a pull request, or apply it to the commit's pull request
+   *
+   * @private
+   *
+   * @param  {Object} note { pr, title, labels, url, text, author }
+   * @param  {Object} commit
+   * @param  {Object} [pr] The pull request the entry points to, or the commit's own
+   *
+   * @return {Object}
+   */
+  _applyCommitNote(note, commit, pr) {
+    const base = pr || {
+      title: commit.subject,
+      labels: [],
+      html_url: `${this._getHtmlUrl()}/${this.repoParams.owner}/${this.repoParams.repo}/commit/${commit.sha}`,
+      text: commit.sha.slice(0, 7),
+      user: { login: "", html_url: "" },
+      body: "",
+      merged_at: commit.date,
+    };
+    const fields = {};
+
+    if (note.title !== undefined) {
+      fields.title = note.title;
+    }
+
+    if (note.labels !== undefined) {
+      fields.labels = [].concat(note.labels).map((name) => ({ name }));
+    }
+
+    if (note.url !== undefined) {
+      fields.html_url = note.url;
+    }
+
+    if (note.text !== undefined) {
+      fields.text = note.text;
+    }
+
+    if (note.author !== undefined) {
+      fields.user = { login: note.author, html_url: `${this._getHtmlUrl()}/${note.author}` };
+    }
+
+    return { ...base, ...fields };
+  }
+
+  /**
+   * Get the web address of the GitHub instance
+   *
+   * @private
+   *
+   * @return {string}
+   */
+  _getHtmlUrl() {
+    const { apiUrl } = this.options;
+
+    return apiUrl ? apiUrl.replace(/\/api\/v3\/?$/, "") : "https://github.com";
+  }
+
+  /**
+   * Print the commits no pull request or commitNotes entry describes, with entries to add
+   *
+   * @private
+   *
+   * @param  {Object[]} unmatched { release, commit }
+   */
+  _reportUnmatchedCommits(unmatched) {
+    if (!unmatched.length) {
+      return;
+    }
+
+    const rows = unmatched.map(
+      ({ release, commit }) => `  ${release}  ${commit.sha.slice(0, 10)}  ${commit.subject}`,
+    );
+    const entries = Object.fromEntries(
+      unmatched.map(({ commit }) => [
+        commit.sha.slice(0, 10),
+        { title: commit.subject, labels: [] },
+      ]),
+    );
+
+    console.warn(
+      chalk.yellow(
+        `\nThese commits have no pull request, so they are not in the release notes:\n\n${rows.join(
+          "\n",
+        )}\n\nTo include them, add entries like these to commitNotes in your gren config. ` +
+          "A cherry-picked commit can take its title and labels from the pull request it came " +
+          'from with { "pr": 330 }. To silence them, match them with ignoreCommitsWith.\n\n',
+      ) + JSON.stringify(entries, null, 2),
+    );
   }
 
   /**
@@ -1077,16 +1575,11 @@ class Gren {
    */
   async _getPullRequestsBlocks(releaseRanges) {
     const loaded = utils.task(this, "Getting all merged pull requests");
-    const since = releaseRanges[releaseRanges.length - 1][1].date;
-    const prs = await this._getMergedPullRequests(since);
-    prs.sort((pr1, pr2) => new Date(pr2.merged_at) - new Date(pr1.merged_at));
-    const filteredPrs = prs.filter(this._filterPullRequest.bind(this));
+    const { lists, unmatched } = await this._getReleasePullRequests(releaseRanges);
 
     let totalPrs = 0;
-    const release = releaseRanges.map((range) => {
-      const filteredPullRequests = filteredPrs.filter(
-        this._filterBlockPullRequest.bind(this, range),
-      );
+    const release = releaseRanges.map((range, index) => {
+      const filteredPullRequests = lists[index];
       totalPrs += filteredPullRequests.length;
       const body = (!range[0].body || this.options.override) && this._groupBy(filteredPullRequests);
       return {
@@ -1098,37 +1591,35 @@ class Gren {
       };
     });
     loaded(`Pull Requests found: ${totalPrs}`);
+    this._reportUnmatchedCommits(unmatched);
     return release;
   }
 
   async _getPullRequestWithIssueBlocks(releaseRanges) {
     const loaded = utils.task(this, "Getting all merged pull requests");
-    const since = releaseRanges[releaseRanges.length - 1][1].date;
     let relevantIssues = [];
 
     const re = new RegExp("([\\w-]+)/([\\w-]+)/issues/([0-9]+)", "gi");
-    const prs = await this._getMergedPullRequests(since);
-    prs.sort((pr1, pr2) => new Date(pr2.merged_at) - new Date(pr1.merged_at));
-
-    const filteredPrs = prs.filter(this._filterPullRequest.bind(this)).map((pr) => {
-      const matches = pr.body.match(re);
-      const relatedIssues =
-        matches &&
-        matches.map((issue) => {
-          const [user, repo, , number] = issue.split("/");
-          return { user, repo, number };
-        });
-      return Object.assign({}, pr, { relatedIssues });
-    });
-
-    const release = releaseRanges.map((range) => {
-      const list = filteredPrs.filter(this._filterBlockPullRequest.bind(this, range));
+    const { lists, unmatched } = await this._getReleasePullRequests(releaseRanges);
+
+    const release = releaseRanges.map((range, index) => {
+      const list = lists[index].map((pr) => {
+        const matches = (pr.body || "").match(re);
+        const relatedIssues =
+          matches &&
+          matches.map((issue) => {
+            const [user, repo, , number] = issue.split("/");
+            return { user, repo, number };
+          });
+        return Object.assign({}, pr, { relatedIssues });
+      });
       list.forEach(({ relatedIssues }) => {
         relevantIssues = relevantIssues.concat(relatedIssues || []);
       });
       loaded(`Pull Requests found: ${list.length}`);
       return Object.assign({}, range, { list });
     });
+    this._reportUnmatchedCommits(unmatched);
 
     const issuesDetails = (
       await Promise.all(relevantIssues.map(this._getSingleIssue.bind(this)))
@@ -1174,8 +1665,7 @@ class Gren {
   _sortReleasesByDate(releaseDates) {
     return Array.from(releaseDates).sort((release1, release2) => {
       if (release1.date == null || release2.date == null) {
-        // compare by semver
-        return cmp(release2.name, release1.name);
+        return compareVersions(release2.name, release1.name);
       } else {
         return new Date(release2.date) - new Date(release1.date);
       }
@@ -1257,10 +1747,12 @@ class Gren {
    * Generate release blocks based on issues or commit messages
    * depending on the option.
    *
+   * @param  {Map<string, string>} [existingSections] The existing changelog's sections by
+   * version, to carry over the releases frozenBefore covers
+   *
    * @return {Promise} Resolving the release blocks
    */
-  async _getReleaseBlocks() {
-    const loadedReleases = utils.task(this, "Getting releases");
+  async _getReleaseBlocks(existingSections) {
     const dataSource = {
       issues: this._getIssueBlocks.bind(this),
       commits: this._getCommitBlocks.bind(this),
@@ -1268,6 +1760,15 @@ class Gren {
       prs: this._getPullRequestsBlocks.bind(this),
       "prs-with-issues": this._getPullRequestWithIssueBlocks.bind(this),
     };
+
+    if (MEMBERSHIP_DATA_SOURCES.includes(this.options.dataSource)) {
+      return this._getMembershipReleaseBlocks(
+        dataSource[this.options.dataSource],
+        existingSections,
+      );
+    }
+
+    const loadedReleases = utils.task(this, "Getting releases");
     const releases = await this._getListReleases();
     this.tasks["Getting releases"].text = "Getting tags";
 
@@ -1331,6 +1832,268 @@ class Gren {
     return dataSource[this.options.dataSource](releaseRanges);
   }
 
+  /**
+   * Generate release blocks from the commits each release contains
+   *
+   * A release contains the commits reachable from its tag but not from any tag with a lower
+   * version, so every commit belongs to the lowest release that contains it. That holds
+   * whichever branch gren runs on, and follows both sides of merges between release lines.
+   *
+   * @private
+   *
+   * @param  {Function} getBlocks The data source that turns release ranges into blocks
+   * @param  {Map<string, string>} [existingSections] See _getReleaseBlocks
+   *
+   * @return {Promise<Object[]>} The release blocks, highest version first
+   */
+  async _getMembershipReleaseBlocks(getBlocks, existingSections) {
+    const releases = await this._getListReleases();
+    const loadedReleases = utils.task(this, "Getting releases");
+    const tags = await this._getVersionTags(releases);
+    const selected = this._selectMembershipReleases(tags);
+
+    loadedReleases(`Releases found: ${selected.map(({ name }) => name).join(", ")}`);
+
+    const cutoff = existingSections && this._getFrozenCutoff();
+    const generated = selected.filter((release) => !(cutoff && Date.parse(release.date) < cutoff));
+
+    // A shallow clone has every tag but not the commits between them, which would leave
+    // pull requests out of the release notes without any way to tell.
+    if (generated.length && git.isShallow()) {
+      throw chalk.red(
+        "\nThe local repository has a truncated history, so the commits in a release cannot be " +
+          'read. Fetch the rest of it with "git fetch --unshallow", or check out with a full ' +
+          'history, e.g. "fetch-depth: 0" for actions/checkout.',
+      );
+    }
+
+    const entries = selected.map((release) => {
+      if (cutoff && Date.parse(release.date) < cutoff) {
+        return { release, frozen: true, verbatim: existingSections.get(release.version) };
+      }
+
+      const lowerTags =
+        release.excludeRefs ||
+        tags.filter((tag) => semver.lt(tag.version, release.version)).map(({ ref }) => ref);
+
+      return { release, commits: git.releaseCommits(release.ref, lowerTags) };
+    });
+    const ranges = entries
+      .filter(({ frozen }) => !frozen)
+      .map(({ release, commits }) => [
+        { id: release.id, name: release.name, date: release.date },
+        { date: commits.length ? commits[commits.length - 1].date : release.date },
+        commits,
+      ]);
+    const blocks = ranges.length ? await getBlocks(ranges) : [];
+    const missing = entries
+      .filter(({ frozen, verbatim }) => frozen && verbatim === undefined)
+      .map(({ release }) => release.name);
+
+    if (missing.length) {
+      console.warn(
+        chalk.yellow(
+          `\nThese releases are before frozenBefore but have no section in the changelog, so they are left out: ${missing.join(", ")}`,
+        ),
+      );
+    }
+
+    return entries
+      .map(({ release, frozen, verbatim }) =>
+        frozen
+          ? verbatim !== undefined && {
+              id: release.id,
+              release: release.name,
+              name: this.options.prefix + release.name,
+              published_at: release.date,
+              verbatim,
+            }
+          : blocks.shift(),
+      )
+      .filter(Boolean);
+  }
+
+  /**
+   * Get the repo's semver tags, highest version first
+   *
+   * Tags come from GitHub and are checked against the local repository, where their commits
+   * are read. Tags matching ignoreTagsWith, and tags that are not semver, are left out.
+   *
+   * @private
+   *
+   * @param  {Object[]} releases The GitHub releases, to find each tag's release
+   *
+   * @return {Promise<Object[]>} Tags as { id, name, version, ref, date }
+   */
+  async _getVersionTags(releases) {
+    const remoteTags = await this.octokit.paginate(this.octokit.rest.repos.listTags, {
+      ...this.repoParams,
+      per_page: 100,
+    });
+    const localTags = git.tagCommits();
+    const missing = [];
+    const moved = [];
+    const byVersion = new Map();
+
+    remoteTags.forEach(({ name, commit }) => {
+      const version = parseVersion(name);
+
+      if (!version || this.options.ignoreTagsWith.some((ignoreTag) => name.match(ignoreTag))) {
+        return;
+      }
+
+      const local = localTags.get(name);
+
+      if (!local) {
+        missing.push(name);
+        return;
+      }
+
+      if (local.sha !== commit.sha) {
+        moved.push(name);
+        return;
+      }
+
+      // When both 1.0.0 and v1.0.0 exist, keep v1.0.0.
+      if (!byVersion.get(version)?.name.startsWith("v")) {
+        const release = releases.find(({ tag_name: tagName }) => tagName === name);
+
+        byVersion.set(version, {
+          id: release ? release.id : null,
+          name,
+          version,
+          ref: `refs/tags/${name}`,
+          date: local.date,
+        });
+      }
+    });
+
+    if (missing.length) {
+      throw chalk.red(
+        `\nThese tags are on GitHub but not in the local repository: ${missing.join(", ")}. ` +
+          'Fetch them, e.g. with "git fetch <remote> --tags", and run gren again.',
+      );
+    }
+
+    if (moved.length) {
+      throw chalk.red(
+        `\nThese local tags point to different commits than on GitHub: ${moved.join(", ")}.`,
+      );
+    }
+
+    return Array.from(byVersion.values()).sort((tag1, tag2) =>
+      semver.rcompare(tag1.version, tag2.version),
+    );
+  }
+
+  /**
+   * Choose the releases to generate: the unreleased version when it has no tag yet, then every
+   * tag with --tags=all, the first tag given with --tags, or otherwise the latest tag
+   *
+   * @private
+   *
+   * @param  {Object[]} tags See _getVersionTags
+   *
+   * @return {Object[]} Releases as { id, name, version, ref, date }, highest version first
+   */
+  _selectMembershipReleases(tags) {
+    const { tags: selectedTags, version, head } = this.options;
+    const releases = [];
+    const unreleasedVersion = parseVersion(version);
+
+    if (head && unreleasedVersion && !tags.some((tag) => tag.version === unreleasedVersion)) {
+      if (!git.refExists(head)) {
+        throw chalk.red(`\nThe branch "${head}" is not in the local repository.`);
+      }
+
+      const merged = git.tagsMergedInto(head);
+      const newer = tags.find(
+        (tag) => merged.has(tag.name) && semver.gte(tag.version, unreleasedVersion),
+      );
+
+      if (newer) {
+        console.warn(
+          chalk.yellow(
+            `\nSkipping the unreleased ${version} section: ${head} already contains ${newer.name}.`,
+          ),
+        );
+      } else {
+        releases.push({
+          id: null,
+          name: version,
+          version: unreleasedVersion,
+          ref: head,
+          date: new Date().toISOString(),
+        });
+      }
+    }
+
+    if (selectedTags.includes("all")) {
+      return releases.concat(tags);
+    }
+
+    // Only one of 1.0.0 and v1.0.0 is kept, as they are the same release, so a tag given with
+    // --tags is matched by version as well as by name.
+    const findTag = (name) =>
+      tags.find((tag) => tag.name === name || (name && tag.version === parseVersion(name)));
+
+    this._validateRequiredTagsExists(
+      selectedTags.filter((name) => findTag(name)).map((name) => ({ tag: { name } })),
+      selectedTags,
+    );
+
+    if (selectedTags.length) {
+      // --tags=new..old is documented as the notes for the new tag using everything since the
+      // old one, which takes in the releases between them rather than only the new tag's own.
+      const selected = findTag(selectedTags[0]);
+      const lower = findTag(selectedTags[1]);
+
+      if (!selected) {
+        return releases;
+      }
+
+      return releases.concat(lower ? { ...selected, excludeRefs: [lower.ref] } : selected);
+    }
+
+    // The latest release is the latest on the branch being released, e.g. 1.2.1 on a 1.x branch
+    // while master is on 2.0.0.
+    const merged = head && git.refExists(head) ? git.tagsMergedInto(head) : null;
+    const latest = (merged && tags.find(({ name }) => merged.has(name))) || tags[0];
+
+    return releases.concat(latest ? [latest] : []);
+  }
+
+  /**
+   * Get the date before which releases are frozen
+   *
+   * @private
+   *
+   * @return {number|null} The time in milliseconds, or null when frozenBefore is not set
+   */
+  _getFrozenCutoff() {
+    const { frozenBefore } = this.options;
+
+    if (!frozenBefore) {
+      return null;
+    }
+
+    if (frozenBefore instanceof Date) {
+      return frozenBefore.getTime();
+    }
+
+    const value = String(frozenBefore);
+
+    if (/^\d{4}-\d{2}-\d{2}/.test(value) && !Number.isNaN(Date.parse(value))) {
+      return Date.parse(value);
+    }
+
+    if (git.refExists(value)) {
+      return Date.parse(git.commitDate(value));
+    }
+
+    throw chalk.red(`\nfrozenBefore must be a date, a tag or a commit SHA: ${value}`);
+  }
+
   _sortCommitsByParent(commits, dateOrder = "desc") {
     // 1) Map sha -> commit
     const commitMap = new Map(commits.map((c) => [c.sha, c]));
diff --git a/lib/src/_git.js b/lib/src/_git.js
new file mode 100644
index 00000000..bc42f607
--- /dev/null
+++ b/lib/src/_git.js
@@ -0,0 +1,147 @@
+import { execFileSync } from "node:child_process";
+
+// Commit ranges can list every commit in a repository.
+const MAX_BUFFER = 256 * 1024 * 1024;
+
+/**
+ * Run a git command in the current working directory
+ *
+ * @param  {string[]} args
+ *
+ * @return {string} The trimmed output
+ */
+function git(args) {
+  return execFileSync("git", args, { encoding: "utf-8", maxBuffer: MAX_BUFFER }).trim();
+}
+
+/**
+ * Split command output into its non-empty lines
+ *
+ * @param  {string} output
+ *
+ * @return {string[]}
+ */
+function lines(output) {
+  return output ? output.split("\n") : [];
+}
+
+/**
+ * Get the commit each local tag points to. Annotated tags are peeled to their commit.
+ *
+ * @return {Map<string, Object>} Tag name to { sha, date }, where date is the commit's
+ * committer date
+ */
+function tagCommits() {
+  const output = git([
+    "for-each-ref",
+    "refs/tags",
+    "--format=%(refname:strip=2)%00%(objectname)%00%(*objectname)%00%(committerdate:iso-strict)%00%(*committerdate:iso-strict)",
+  ]);
+
+  return new Map(
+    lines(output).map((line) => {
+      const [name, object, peeled, date, peeledDate] = line.split("\0");
+
+      return [name, { sha: peeled || object, date: peeledDate || date }];
+    }),
+  );
+}
+
+/**
+ * Get the names of the tags reachable from a ref
+ *
+ * @param  {string} ref
+ *
+ * @return {Set<string>}
+ */
+function tagsMergedInto(ref) {
+  return new Set(lines(git(["tag", "--merged", ref])));
+}
+
+/**
+ * Get the commits reachable from a ref but not from any of the excluded refs, newest first.
+ *
+ * @param  {string} ref
+ * @param  {string[]} excludeRefs
+ *
+ * @return {Object[]} Commits as { sha, parents, date, author, subject }
+ */
+function releaseCommits(ref, excludeRefs = []) {
+  const output = git([
+    "log",
+    "--format=%H%x00%P%x00%cI%x00%an%x00%s",
+    ref,
+    "--not",
+    ...excludeRefs,
+    "--",
+  ]);
+
+  return lines(output).map((line) => {
+    const [sha, parents, date, author, subject] = line.split("\0");
+
+    return { sha, parents: parents ? parents.split(" ") : [], date, author, subject };
+  });
+}
+
+/**
+ * Get the commits a merge commit brought in from its second parent
+ *
+ * @param  {string} sha
+ *
+ * @return {string[]} The commit SHAs, or an empty Array when the commit is not a merge
+ */
+function mergeBranchCommits(sha) {
+  const [, , secondParent] = git(["rev-list", "--parents", "-n", "1", sha]).split(" ");
+
+  if (!secondParent) {
+    return [];
+  }
+
+  return lines(git(["rev-list", `${sha}^1..${secondParent}`]));
+}
+
+/**
+ * Get the committer date of a ref
+ *
+ * @param  {string} ref A tag, branch or SHA
+ *
+ * @return {string} The ISO 8601 date
+ */
+function commitDate(ref) {
+  return git(["log", "-1", "--format=%cI", `${ref}^{commit}`, "--"]);
+}
+
+/**
+ * Check whether the repository has a truncated history, as a shallow clone does
+ *
+ * @return {boolean}
+ */
+function isShallow() {
+  return git(["rev-parse", "--is-shallow-repository"]) === "true";
+}
+
+/**
+ * Check whether a ref resolves to a commit
+ *
+ * @param  {string} ref
+ *
+ * @return {boolean}
+ */
+function refExists(ref) {
+  try {
+    git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  tagCommits,
+  tagsMergedInto,
+  releaseCommits,
+  mergeBranchCommits,
+  commitDate,
+  isShallow,
+  refExists,
+};
diff --git a/package-lock.json b/package-lock.json
index 29d92782..ac1162dd 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -19,7 +19,7 @@
         "object-assign-deep": "^0.4.0",
         "prettier": "^3.9.6",
         "require-from-url": "^3.1.3",
-        "semver-compare": "^1.0.0",
+        "semver": "^7.8.5",
         "yaml": "^2.9.0"
       },
       "bin": {
@@ -4040,7 +4040,6 @@
       "version": "7.8.5",
       "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
       "integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
-      "dev": true,
       "license": "ISC",
       "bin": {
         "semver": "bin/semver.js"
@@ -4049,12 +4048,6 @@
         "node": ">=10"
       }
     },
-    "node_modules/semver-compare": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/semver-compare/-/semver-compare-1.0.0.tgz",
-      "integrity": "sha512-YM3/ITh2MJ5MtzaM429anh+x2jiLVjqILF4m4oyQB18W7Ggea7BfqdH/wGMK7dDiMghv/6WG7znWMwUDzJiXow==",
-      "license": "MIT"
-    },
     "node_modules/serialize-javascript": {
       "version": "7.1.1",
       "resolved": "https://registry.npmjs.org/serialize-javascript/-/serialize-javascript-7.1.1.tgz",
diff --git a/package.json b/package.json
index d08dfd7c..064e8ac9 100644
--- a/package.json
+++ b/package.json
@@ -72,7 +72,7 @@
     "object-assign-deep": "^0.4.0",
     "prettier": "^3.9.6",
     "require-from-url": "^3.1.3",
-    "semver-compare": "^1.0.0",
+    "semver": "^7.8.5",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
diff --git a/test/Gren.membership.spec.js b/test/Gren.membership.spec.js
new file mode 100644
index 00000000..e8b18bca
--- /dev/null
+++ b/test/Gren.membership.spec.js
@@ -0,0 +1,678 @@
+import { assert } from "chai";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import Gren from "../lib/src/Gren.js";
+import * as git from "../lib/src/_git.js";
+import { createReleaseRepo } from "./fixtures/release-repo.js";
+
+const ALL_TAGS = ["v2.0.0", "v1.2.1", "v1.2.0", "v1.1.1", "v1.1.0", "v1.0.0", "1.0.0", "V1"];
+const TAGS_BEFORE_1_2_0 = ["v1.1.1", "v1.1.0", "v1.0.0", "1.0.0", "V1"];
+
+describe("Gren release membership", () => {
+  let repo;
+  let cwd;
+  let pulls;
+  let associated;
+  let calls;
+  let warnings;
+  const originalWarn = console.warn;
+
+  const day = (n) => new Date(Date.UTC(2020, 0, n)).toISOString();
+  const pullRequest = (number, sha, mergedDay, { repoName = "owner/current", ...refs } = {}) => ({
+    number,
+    title: `PR ${number}`,
+    html_url: `https://github.com/${repoName}/pull/${number}`,
+    merge_commit_sha: sha,
+    merged_at: day(mergedDay),
+    updated_at: day(mergedDay),
+    labels: (refs.labels || []).map((name) => ({ name })),
+    user: { login: "someone", html_url: "https://github.com/someone" },
+    body: "",
+    base: { ref: refs.base || "master", repo: { full_name: repoName } },
+    head: { ref: refs.head || `branch-${number}`, repo: { full_name: repoName } },
+  });
+
+  /**
+   * Create a Gren for the fixture repository, with GitHub stubbed
+   *
+   * @param  {Object} options Gren options, plus remoteTags: the tags GitHub reports
+   *
+   * @return {Gren}
+   */
+  const createGren = ({ remoteTags = ALL_TAGS, ...options } = {}) => {
+    const gren = new Gren({
+      token: "test-token",
+      username: "owner",
+      repo: "current",
+      quiet: true,
+      dataSource: "prs",
+      tags: "all",
+      head: "master",
+      version: "2.1.0",
+      ignoreCommitsWith: ["^Release ", "^Initial commit"],
+      pullRequestRepos: ["owner/old"],
+      template: { issue: "{{text}} {{name}} {{url}}" },
+      ...options,
+    });
+    const localTags = git.tagCommits();
+
+    gren.octokit = {
+      paginate: async (method, params) => (await method(params)).data,
+      rest: {
+        repos: {
+          listReleases: async () => ({ headers: {}, data: [] }),
+          listTags: async () => ({
+            data: remoteTags.map((name) => ({
+              name,
+              commit: { sha: localTags.has(name) ? localTags.get(name).sha : "0".repeat(40) },
+            })),
+          }),
+          listPullRequestsAssociatedWithCommit: async ({ owner, repo: name, commit_sha: sha }) => {
+            calls.push(`${owner}/${name}:${sha}`);
+
+            // GitHub answers 422, not 404, for a commit that is not in the repo, which is the
+            // usual answer for a repo in pullRequestRepos.
+            if (name !== "current" && !associated[`${owner}/${name}`]?.[sha]) {
+              const error = new Error(`No commit found for SHA: ${sha}`);
+
+              error.status = 422;
+              throw error;
+            }
+
+            return { data: associated[`${owner}/${name}`]?.[sha] || [] };
+          },
+        },
+        pulls: {
+          list: async ({ owner, repo: name }) => ({
+            headers: {},
+            data: pulls[`${owner}/${name}`] || [],
+          }),
+          get: async ({ owner, repo: name, pull_number: number }) => {
+            const pr = (pulls[`${owner}/${name}`] || []).find((item) => item.number === number);
+
+            if (!pr) {
+              const error = new Error("Not Found");
+
+              error.status = 404;
+              throw error;
+            }
+
+            return { data: pr };
+          },
+        },
+      },
+    };
+
+    return gren;
+  };
+  const byRelease = (blocks) => Object.fromEntries(blocks.map((block) => [block.release, block]));
+  const numbers = (block) => [...block.body.matchAll(/#(\d+)/g)].map((match) => Number(match[1]));
+
+  before(() => {
+    repo = createReleaseRepo();
+    cwd = process.cwd();
+    process.chdir(repo.dir);
+  });
+
+  after(() => {
+    process.chdir(cwd);
+    repo.remove();
+  });
+
+  beforeEach(() => {
+    const { sha } = repo;
+    const pr5 = pullRequest(5, sha.c8b, 12);
+
+    pulls = {
+      "owner/current": [
+        pullRequest(2, sha.c3, 5, { base: "1.x" }),
+        pullRequest(3, sha.c4, 6),
+        pullRequest(4, sha.m1, 9, { head: "feature" }),
+        pr5,
+        pullRequest(6, sha.m2, 14, { base: "1.x", head: "master", labels: ["sync"] }),
+        pullRequest(7, sha.c10, 15),
+        pullRequest(8, sha.c11, 16, { base: "1.x" }),
+        pullRequest(9, sha.c12, 17),
+      ],
+      "owner/old": [pullRequest(1, sha.c2, 3, { repoName: "owner/old" })],
+    };
+    // A rebase merge: only the last commit is the pull request's merge commit.
+    associated = { "owner/current": { [sha.c8a]: [pr5] } };
+    calls = [];
+    warnings = [];
+    console.warn = (...args) => warnings.push(args.join(" "));
+  });
+
+  afterEach(() => {
+    console.warn = originalWarn;
+  });
+
+  describe("_getReleaseBlocks", () => {
+    it("Should put each commit in the lowest release that contains it", async () => {
+      const blocks = await createGren()._getReleaseBlocks();
+      const releases = byRelease(blocks);
+
+      assert.deepEqual(
+        blocks.map(({ release }) => release),
+        ["2.1.0", "v2.0.0", "v1.2.1", "v1.2.0", "v1.1.1", "v1.1.0", "v1.0.0"],
+        "Highest version first, with duplicate and non-semver tags left out",
+      );
+      assert.deepEqual(numbers(releases["2.1.0"]), [9]);
+      assert.deepEqual(numbers(releases["v2.0.0"]), [7]);
+      assert.deepEqual(numbers(releases["v1.2.1"]), [8], "Released after 2.0.0");
+      assert.deepEqual(numbers(releases["v1.2.0"]), [6, 5, 4, 3], "Newest first, no duplicates");
+      assert.deepEqual(numbers(releases["v1.1.1"]), [2]);
+      assert.deepEqual(numbers(releases["v1.1.0"]), [1]);
+      assert.include(releases["v1.0.0"].body, "No changelog for this release");
+    });
+
+    it("Should give the same tagged sections on every branch", async () => {
+      const tagged = (blocks) => blocks.filter(({ release }) => release.startsWith("v"));
+      const fromMaster = await createGren()._getReleaseBlocks();
+      const fromReleaseLine = await createGren({
+        head: "1.x",
+        version: "1.2.1",
+      })._getReleaseBlocks();
+
+      assert.deepEqual(tagged(fromReleaseLine), tagged(fromMaster));
+      assert.notInclude(
+        fromReleaseLine.map(({ release }) => release),
+        "1.2.1",
+        "No unreleased section for a tagged version",
+      );
+    });
+
+    it("Should build a release cut from master", async () => {
+      const blocks = await createGren({
+        remoteTags: TAGS_BEFORE_1_2_0,
+        head: "before-sync",
+        version: "1.2.0",
+      })._getReleaseBlocks();
+
+      assert.deepEqual(numbers(byRelease(blocks)["1.2.0"]), [5, 4, 3]);
+    });
+
+    it("Should include master's pull requests in a release made after syncing master", async () => {
+      const blocks = await createGren({
+        remoteTags: TAGS_BEFORE_1_2_0,
+        head: "after-sync",
+        version: "1.2.0",
+      })._getReleaseBlocks();
+
+      assert.deepEqual(numbers(byRelease(blocks)["1.2.0"]), [6, 5, 4, 3]);
+    });
+
+    it("Should leave out of the next major what a sync already released", async () => {
+      const blocks = await createGren({
+        remoteTags: ["v1.2.0", ...TAGS_BEFORE_1_2_0],
+        head: repo.sha.c10,
+        version: "2.0.0",
+      })._getReleaseBlocks();
+
+      assert.deepEqual(numbers(byRelease(blocks)["2.0.0"]), [7]);
+    });
+
+    it("Should find pull requests in pullRequestRepos", async () => {
+      const withRepos = byRelease(await createGren()._getReleaseBlocks());
+      const withoutRepos = byRelease(
+        await createGren({ pullRequestRepos: [] })._getReleaseBlocks(),
+      );
+
+      assert.include(withRepos["v1.1.0"].body, "https://github.com/owner/old/pull/1");
+      assert.deepEqual(numbers(withoutRepos["v1.1.0"]), []);
+      assert.match(warnings.join("\n"), /v1\.1\.0 {2}\w{10} {2}Add feature A \(#1\)/);
+    });
+
+    it("Should report commits without a pull request, but not merge-commit branches or syncs", async () => {
+      const { sha } = repo;
+
+      await createGren()._getReleaseBlocks();
+
+      const report = warnings.join("\n");
+
+      assert.include(report, `v1.2.0  ${sha.c7.slice(0, 10)}  Fix a security issue`);
+      assert.include(report, `"${sha.c7.slice(0, 10)}": {\n    "title": "Fix a security issue"`);
+      assert.notInclude(report, "Start feature D", "Covered by its merge-commit pull request");
+      assert.notInclude(report, "Release 1.2.0", "Matched by ignoreCommitsWith");
+      assert.sameMembers(
+        calls,
+        [`owner/current:${sha.c8a}`, `owner/current:${sha.c7}`, `owner/old:${sha.c7}`],
+        "The next repo is only searched when a commit is not found",
+      );
+    });
+
+    it("Should add commitNotes entries and apply them to pull requests", async () => {
+      const { sha } = repo;
+      const blocks = await createGren({
+        commitNotes: {
+          [sha.c7.slice(0, 8)]: {
+            title: "Fix CVE-2020-0001",
+            labels: ["security"],
+            url: "https://example.com/advisory",
+            text: "GHSA-1234",
+          },
+          [sha.c4.slice(0, 7)]: { title: "Feature C, renamed" },
+        },
+      })._getReleaseBlocks();
+
+      assert.deepEqual(byRelease(blocks)["v1.2.0"].body.split("\n").filter(Boolean), [
+        "#6 PR 6 https://github.com/owner/current/pull/6",
+        "#5 PR 5 https://github.com/owner/current/pull/5",
+        "GHSA-1234 Fix CVE-2020-0001 https://example.com/advisory",
+        "#4 PR 4 https://github.com/owner/current/pull/4",
+        "#3 Feature C, renamed https://github.com/owner/current/pull/3",
+      ]);
+      assert.notInclude(warnings.join("\n"), "Fix a security issue");
+    });
+
+    it("Should keep a commitNotes entry when other commits match the same pull request", async () => {
+      const { sha } = repo;
+      // c8b is pull request 5's merge commit, c8a another of its commits, found by lookup.
+      const notes = { [sha.c8b.slice(0, 8)]: { title: "PR 5, corrected", labels: ["security"] } };
+      const blocks = await createGren({ commitNotes: notes })._getReleaseBlocks();
+
+      assert.deepEqual(byRelease(blocks)["v1.2.0"].body.split("\n").filter(Boolean), [
+        "#6 PR 6 https://github.com/owner/current/pull/6",
+        "#5 PR 5, corrected https://github.com/owner/current/pull/5",
+        "#4 PR 4 https://github.com/owner/current/pull/4",
+        "#3 PR 3 https://github.com/owner/current/pull/3",
+      ]);
+    });
+
+    it("Should list a pull request once when a commitNotes entry gives it another url", async () => {
+      const { sha } = repo;
+      const notes = {
+        [sha.c8b.slice(0, 8)]: { title: "PR 5, corrected", url: "https://example.com/x" },
+      };
+      const blocks = await createGren({ commitNotes: notes })._getReleaseBlocks();
+
+      assert.deepEqual(numbers(byRelease(blocks)["v1.2.0"]), [6, 5, 4, 3]);
+      assert.include(byRelease(blocks)["v1.2.0"].body, "PR 5, corrected https://example.com/x");
+    });
+
+    it("Should take a commitNotes entry from the pull request it points to", async () => {
+      const { sha } = repo;
+      // c7 stands in for a commit cherry-picked from another release line.
+      const notes = { [sha.c7.slice(0, 8)]: { pr: "owner/old#1" } };
+      const blocks = await createGren({ commitNotes: notes })._getReleaseBlocks();
+      const block = byRelease(blocks)["v1.2.0"];
+
+      assert.include(block.body, "#1 PR 1 https://github.com/owner/old/pull/1");
+      assert.notInclude(warnings.join("\n"), "Fix a security issue");
+    });
+
+    it("Should let a commitNotes entry override the pull request it points to", async () => {
+      const { sha } = repo;
+      const notes = {
+        [sha.c7.slice(0, 8)]: { pr: 8, title: "Fix E, cherry-picked", labels: ["security"] },
+      };
+      const blocks = await createGren({ commitNotes: notes })._getReleaseBlocks();
+      const block = byRelease(blocks)["v1.2.0"];
+
+      assert.include(block.body, "#8 Fix E, cherry-picked https://github.com/owner/current/pull/8");
+    });
+
+    it("Should list a pull request once when a commitNotes entry points to it", async () => {
+      const { sha } = repo;
+      // Pull request 3 is already in v1.2.0, as the pull request commit c4 was merged in. The
+      // one entry sits where c7 is, as that is when the change reached this release.
+      const notes = { [sha.c7.slice(0, 8)]: { pr: "#3" } };
+      const blocks = await createGren({ commitNotes: notes })._getReleaseBlocks();
+      const block = byRelease(blocks)["v1.2.0"];
+
+      assert.deepEqual(numbers(block), [6, 5, 3, 4]);
+    });
+
+    it("Should stop when a commitNotes entry points to a pull request that is not there", async () => {
+      const { sha } = repo;
+      const notes = { [sha.c7.slice(0, 8)]: { pr: 404 } };
+
+      try {
+        await createGren({ commitNotes: notes })._getReleaseBlocks();
+        assert.fail("A missing pull request should stop the changelog");
+      } catch (error) {
+        assert.include(String(error), "Could not get owner/current#404");
+      }
+    });
+
+    it("Should stop when a pull request lookup fails for a reason other than a missing commit", async () => {
+      const gren = createGren();
+      const error = new Error("API rate limit exceeded");
+
+      error.status = 403;
+      gren.octokit.rest.repos.listPullRequestsAssociatedWithCommit = async () => {
+        throw error;
+      };
+
+      try {
+        await gren._getReleaseBlocks();
+        assert.fail("A failed lookup should stop the changelog");
+      } catch (error) {
+        assert.include(String(error), "Could not look up the pull request");
+        assert.include(String(error), "API rate limit exceeded");
+      }
+    });
+
+    it("Should keep looking in other repos when a lookup only finds a branch sync", async () => {
+      const { sha } = repo;
+      const sync = pulls["owner/current"].find(({ number }) => number === 6);
+      const upstream = pullRequest(1, sha.c2, 3, { repoName: "owner/old" });
+
+      // c7 arrived in this repo through the sync, but it belongs to a pull request upstream.
+      associated["owner/current"][sha.c7] = [sync];
+      associated["owner/old"] = { [sha.c7]: [upstream] };
+
+      const blocks = await createGren()._getReleaseBlocks();
+
+      assert.include(
+        byRelease(blocks)["v1.2.0"].body,
+        "#1 PR 1 https://github.com/owner/old/pull/1",
+      );
+      assert.notInclude(warnings.join("\n"), sha.c7.slice(0, 10));
+    });
+
+    it("Should stop when a repo in pullRequestRepos is not there", async () => {
+      const gren = createGren();
+      const lookUp = gren.octokit.rest.repos.listPullRequestsAssociatedWithCommit;
+
+      gren.octokit.rest.repos.listPullRequestsAssociatedWithCommit = async (params) => {
+        if (params.repo === "old") {
+          const error = new Error("Not Found");
+
+          error.status = 404;
+          throw error;
+        }
+
+        return lookUp(params);
+      };
+
+      try {
+        await gren._getReleaseBlocks();
+        assert.fail("A missing repo should stop the changelog");
+      } catch (error) {
+        assert.include(String(error), "Could not look up the pull request");
+        assert.include(String(error), "owner/old");
+      }
+    });
+
+    it("Should leave out pull requests with an ignored label", async () => {
+      const blocks = await createGren({ ignoreIssuesWith: ["sync"] })._getReleaseBlocks();
+
+      assert.deepEqual(numbers(byRelease(blocks)["v1.2.0"]), [5, 4, 3]);
+    });
+
+    it("Should work for the prs-with-issues data source", async () => {
+      const blocks = await createGren({ dataSource: "prs-with-issues" })._getReleaseBlocks();
+
+      assert.deepEqual(numbers(byRelease(blocks)["v1.2.0"]), [6, 5, 4, 3]);
+    });
+
+    it("Should skip an unreleased version the branch has already passed", async () => {
+      const blocks = await createGren({ version: "1.1.5" })._getReleaseBlocks();
+
+      assert.notInclude(
+        blocks.map(({ release }) => release),
+        "1.1.5",
+      );
+      assert.include(warnings.join("\n"), "Skipping the unreleased 1.1.5 section");
+    });
+
+    it("Should generate only the tag given with --tags, or the latest tag", async () => {
+      const selected = await createGren({ tags: "v1.1.1", version: "2.0.0" })._getReleaseBlocks();
+      const latest = await createGren({ tags: [] })._getReleaseBlocks();
+
+      assert.deepEqual(
+        selected.map(({ release }) => release),
+        ["v1.1.1"],
+      );
+      assert.deepEqual(
+        latest.map(({ release }) => release),
+        ["2.1.0", "v2.0.0"],
+      );
+    });
+
+    it("Should take a tag given by either of its names", async () => {
+      // The fixture has both 1.0.0 and v1.0.0 on the same commit, and only v1.0.0 is kept.
+      const one = await createGren({ tags: "1.0.0" })._getReleaseBlocks();
+      const range = await createGren({ tags: ["v1.2.0", "1.0.0"] })._getReleaseBlocks();
+
+      assert.deepEqual(
+        one.map(({ release }) => release),
+        ["2.1.0", "v1.0.0"],
+      );
+      assert.deepEqual(
+        numbers(byRelease(range)["v1.2.0"]),
+        [6, 5, 4, 3, 2, 1],
+        "Everything since the tag given, by its other name",
+      );
+    });
+
+    it("Should take the latest tag from the branch being released", async () => {
+      const blocks = await createGren({
+        tags: [],
+        head: "1.x",
+        version: "1.2.1",
+      })._getReleaseBlocks();
+
+      assert.deepEqual(
+        blocks.map(({ release }) => release),
+        ["v1.2.1"],
+        "The latest release of a maintenance line, not the highest version anywhere",
+      );
+    });
+
+    it("Should generate a tag back to the second tag given with --tags", async () => {
+      const blocks = await createGren({ tags: ["v1.2.0", "v1.0.0"] })._getReleaseBlocks();
+      const v120 = byRelease(blocks)["v1.2.0"];
+
+      assert.deepEqual(numbers(v120), [6, 5, 4, 3, 2, 1], "Everything since the tag given");
+    });
+
+    it("Should apply overridePrs to the pull requests commit lookups find", async () => {
+      const { sha } = repo;
+      // c8a is found by lookup, and is a commit of pull request 5, whose merge commit is c8b.
+      const renamed = await createGren({
+        overridePrs: (prs) =>
+          prs.map((pr) => (pr.number === 5 ? { ...pr, title: "PR 5, overridden" } : pr)),
+      })._getReleaseBlocks();
+      const dropped = await createGren({
+        overridePrs: (prs) => prs.filter((pr) => pr.number !== 5),
+      })._getReleaseBlocks();
+
+      assert.include(byRelease(renamed)["v1.2.0"].body, "PR 5, overridden");
+      assert.deepEqual(numbers(byRelease(dropped)["v1.2.0"]), [6, 4, 3]);
+      assert.include(warnings.join("\n"), sha.c8a.slice(0, 10), "The commit is reported instead");
+    });
+
+    it("Should fail when tags are missing locally or point elsewhere", async () => {
+      const missing = createGren({ remoteTags: ["v9.9.9", ...ALL_TAGS] });
+      const moved = createGren();
+
+      moved.octokit.rest.repos.listTags = async () => ({
+        data: [{ name: "v1.1.1", commit: { sha: repo.sha.c4 } }],
+      });
+
+      try {
+        await missing._getReleaseBlocks();
+        assert.fail("Missing tags should fail");
+      } catch (error) {
+        assert.include(String(error), "not in the local repository: v9.9.9");
+      }
+
+      try {
+        await moved._getReleaseBlocks();
+        assert.fail("Moved tags should fail");
+      } catch (error) {
+        assert.include(String(error), "point to different commits than on GitHub: v1.1.1");
+      }
+    });
+
+    it("Should stop when the local repository has a truncated history", async () => {
+      const shallow = fs.mkdtempSync(path.join(os.tmpdir(), "gren-shallow-"));
+
+      execFileSync("git", [
+        "clone",
+        "--quiet",
+        "--depth",
+        "1",
+        "--branch",
+        "v1.2.0",
+        `file://${repo.dir}`,
+        shallow,
+      ]);
+      execFileSync("git", [
+        "-C",
+        shallow,
+        "fetch",
+        "--quiet",
+        "--depth",
+        "1",
+        "origin",
+        "+refs/tags/*:refs/tags/*",
+      ]);
+      process.chdir(shallow);
+
+      try {
+        // Every tag is here and points where GitHub says, but the commits between them are not.
+        await createGren({ tags: "v1.2.0", version: "1.2.0" })._getReleaseBlocks();
+        assert.fail("A shallow clone should stop the changelog");
+      } catch (error) {
+        assert.include(String(error), "truncated history");
+      } finally {
+        process.chdir(repo.dir);
+        fs.rmSync(shallow, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("frozenBefore", () => {
+    const separator = "\n---\n\n";
+    const sections = {
+      "2.0.0": "## v2.0.0 (2020-01-15)\n\nOld notes for 2.0.0\n",
+      "1.2.0": "## v1.2.0 (2020-01-14)\n\nHand-written 1.2.0 notes\n",
+      "1.1.1": "## v1.1.1 (2020-01-05)\n\n#2 Fix bug B\n",
+      unversioned: "## 1.x maintenance (2020-01-05)\n\nNotes without a version\n",
+      "1.1.0": "## v1.1.0 (2020-01-04)\n\n#1 Add feature A\n",
+    };
+
+    beforeEach(() => {
+      fs.writeFileSync(
+        path.join(repo.dir, "CHANGELOG.md"),
+        "# Changelog\n\n" + Object.values(sections).join(separator),
+      );
+    });
+
+    afterEach(() => {
+      fs.rmSync(path.join(repo.dir, "CHANGELOG.md"), { force: true });
+    });
+
+    [
+      ["a commit", () => repo.sha.c10],
+      ["a date", () => "2020-01-15"],
+    ].forEach(([kind, cutoff]) => {
+      it(`Should copy releases before ${kind} from the existing changelog`, async () => {
+        const gren = createGren({ frozenBefore: cutoff(), changelogFilename: "CHANGELOG.md" });
+        const blocks = await gren._getReleaseBlocks(gren._readChangelogSections());
+        const releases = byRelease(blocks);
+
+        assert.deepEqual(
+          blocks.map(({ release }) => release),
+          ["2.1.0", "v2.0.0", "v1.2.1", "v1.2.0", "v1.1.1", "v1.1.0"],
+        );
+        assert.deepEqual(numbers(releases["v2.0.0"]), [7], "Not before the cutoff, so rebuilt");
+        assert.equal(releases["v1.2.0"].verbatim, sections["1.2.0"]);
+        assert.equal(
+          releases["v1.1.1"].verbatim,
+          sections["1.1.1"] + separator + sections.unversioned,
+          "A section without a version stays with the one before it",
+        );
+        assert.equal(releases["v1.1.0"].verbatim, sections["1.1.0"]);
+        assert.include(
+          warnings.join("\n"),
+          "no section in the changelog, so they are left out: v1.0.0",
+        );
+        assert.deepEqual(calls, [], "Commits in frozen releases are not looked up");
+        assert.include(
+          gren._templateReleases(blocks),
+          [sections["1.2.0"], sections["1.1.1"], sections.unversioned, sections["1.1.0"]].join(
+            separator,
+          ),
+        );
+      });
+    });
+
+    it("Should read a changelog with nothing between its releases", async () => {
+      const plain = { "2.0.0": sections["2.0.0"], "1.2.0": sections["1.2.0"] };
+
+      fs.writeFileSync(
+        path.join(repo.dir, "CHANGELOG.md"),
+        "# Changelog\n\n" + Object.values(plain).join(""),
+      );
+
+      const gren = createGren({
+        frozenBefore: "2020-01-16",
+        changelogFilename: "CHANGELOG.md",
+        template: { issue: "{{text}} {{name}} {{url}}", releaseSeparator: "" },
+      });
+      const blocks = await gren._getReleaseBlocks(gren._readChangelogSections());
+
+      assert.equal(byRelease(blocks)["v2.0.0"].verbatim, plain["2.0.0"]);
+      assert.equal(byRelease(blocks)["v1.2.0"].verbatim, plain["1.2.0"]);
+    });
+
+    it("Should stop when no releases can be read from the changelog", () => {
+      fs.writeFileSync(path.join(repo.dir, "CHANGELOG.md"), "# Changelog\n\nNothing to go on.\n");
+
+      const gren = createGren({ frozenBefore: "2020-01-16", changelogFilename: "CHANGELOG.md" });
+
+      // Generating would otherwise write the file with every frozen release missing from it.
+      assert.throws(() => gren._readChangelogSections(), /No releases could be read/);
+    });
+
+    it("Should reject a value that is not a date, tag or commit", async () => {
+      const gren = createGren({ frozenBefore: "not-a-ref" });
+
+      try {
+        await gren._getReleaseBlocks(gren._readChangelogSections());
+        assert.fail("An invalid frozenBefore should fail");
+      } catch (error) {
+        assert.include(String(error), "frozenBefore must be a date, a tag or a commit SHA");
+      }
+    });
+  });
+
+  describe("Options", () => {
+    it("Should reject pullRequestRepos entries that are not owner/repo", () => {
+      assert.throws(() => createGren({ pullRequestRepos: ["just-a-name"] }), /owner\/repo/);
+    });
+
+    it("Should reject commitNotes keys that are not commit SHAs", () => {
+      assert.throws(() => createGren({ commitNotes: { abc: {} } }), /at least 7 characters/);
+    });
+
+    it("Should reject a commitNotes pr that is not a pull request reference", () => {
+      const notes = (pr) => ({ commitNotes: { abcdef1: { pr } } });
+
+      assert.throws(() => createGren(notes("owner/repo/330")), /owner\/repo#123/);
+      assert.throws(() => createGren(notes("#0")), /owner\/repo#123/);
+      assert.throws(() => createGren(notes("")), /owner\/repo#123/);
+      assert.doesNotThrow(() => createGren(notes("owner/repo#330")));
+      assert.doesNotThrow(() => createGren(notes(330)));
+    });
+  });
+
+  describe("_sortReleasesByDate", () => {
+    it("Should compare names by semver when dates are missing", () => {
+      const releases = ["v1.9.0", "V1", "v2.0.0", "v1.10.0"].map((name) => ({ name }));
+
+      assert.deepEqual(
+        createGren()
+          ._sortReleasesByDate(releases)
+          .map(({ name }) => name),
+        ["v2.0.0", "v1.10.0", "v1.9.0", "V1"],
+      );
+    });
+  });
+});
diff --git a/test/_git.spec.js b/test/_git.spec.js
new file mode 100644
index 00000000..aef79ce0
--- /dev/null
+++ b/test/_git.spec.js
@@ -0,0 +1,119 @@
+import { assert } from "chai";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import * as git from "../lib/src/_git.js";
+import { createReleaseRepo } from "./fixtures/release-repo.js";
+
+describe("_git.js", () => {
+  let repo;
+  let cwd;
+
+  before(() => {
+    repo = createReleaseRepo();
+    cwd = process.cwd();
+    process.chdir(repo.dir);
+  });
+
+  after(() => {
+    process.chdir(cwd);
+    repo.remove();
+  });
+
+  describe("tagCommits", () => {
+    it("Should peel annotated tags to their commit and its date", () => {
+      const tags = git.tagCommits();
+
+      assert.deepEqual(tags.get("v1.0.0"), { sha: repo.sha.c1, date: "2020-01-01T00:00:00+00:00" });
+      assert.equal(tags.get("1.0.0").sha, repo.sha.c1, "A lightweight tag");
+      assert.equal(tags.get("v1.2.0").sha, repo.sha.m2);
+    });
+  });
+
+  describe("tagsMergedInto", () => {
+    it("Should list the tags reachable from a ref", () => {
+      const tags = git.tagsMergedInto("master");
+
+      assert.isTrue(tags.has("v2.0.0"));
+      assert.isFalse(tags.has("v1.1.1"), "A tag on the other release line");
+    });
+  });
+
+  describe("releaseCommits", () => {
+    it("Should follow both parents of a merge and leave out excluded refs", () => {
+      const commits = git.releaseCommits("v1.2.0", ["v1.1.1", "v1.1.0", "v1.0.0"]);
+      const { sha } = repo;
+
+      assert.sameMembers(
+        commits.map((commit) => commit.sha),
+        [sha.m2, sha.c9, sha.c8b, sha.c8a, sha.c7, sha.m1, sha.c6, sha.c5, sha.c4],
+      );
+    });
+
+    it("Should describe each commit", () => {
+      const [commit] = git.releaseCommits("v1.1.1", ["v1.1.0"]);
+
+      assert.deepEqual(commit, {
+        sha: repo.sha.c3,
+        parents: [repo.sha.c2],
+        date: "2020-01-05T00:00:00+00:00",
+        author: "Test",
+        subject: "Fix bug B (#2)",
+      });
+    });
+  });
+
+  describe("mergeBranchCommits", () => {
+    it("Should list the commits a merge brought in", () => {
+      assert.sameMembers(git.mergeBranchCommits(repo.sha.m1), [repo.sha.c5, repo.sha.c6]);
+    });
+
+    it("Should return nothing for a commit that is not a merge", () => {
+      assert.deepEqual(git.mergeBranchCommits(repo.sha.c4), []);
+    });
+  });
+
+  describe("commitDate", () => {
+    it("Should return the committer date of a tag's commit", () => {
+      assert.equal(git.commitDate("v1.0.0"), "2020-01-01T00:00:00+00:00");
+    });
+  });
+
+  describe("isShallow", () => {
+    it("Should tell whether the repository's history is truncated", () => {
+      const clone = fs.mkdtempSync(path.join(os.tmpdir(), "gren-shallow-"));
+
+      execFileSync("git", [
+        "clone",
+        "--quiet",
+        "--depth",
+        "1",
+        "--branch",
+        "v1.2.0",
+        `file://${repo.dir}`,
+        clone,
+      ]);
+
+      assert.isFalse(git.isShallow(), "The fixture repository");
+
+      process.chdir(clone);
+
+      try {
+        assert.isTrue(git.isShallow());
+        assert.equal(git.releaseCommits("v1.2.0").length, 1, "Its history stops at the clone");
+      } finally {
+        process.chdir(repo.dir);
+        fs.rmSync(clone, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("refExists", () => {
+    it("Should tell whether a ref resolves to a commit", () => {
+      assert.isTrue(git.refExists("1.x"));
+      assert.isTrue(git.refExists(repo.sha.c7.slice(0, 10)));
+      assert.isFalse(git.refExists("no-such-branch"));
+    });
+  });
+});
diff --git a/test/fixtures/release-repo.js b/test/fixtures/release-repo.js
new file mode 100644
index 00000000..30b89ddc
--- /dev/null
+++ b/test/fixtures/release-repo.js
@@ -0,0 +1,94 @@
+// Builds a throwaway git repository with two release lines, for testing how
+// gren assigns commits to releases.
+//
+//   master  c1 (v1.0.0) - c2 (v1.1.0) - c4 - m1 - c7 - c8a - c8b - c9 - c10 (v2.0.0) - c12
+//                           \            \_c5-c6_/                 \
+//   1.x                      c3 (v1.1.1) -------------------------- m2 (v1.2.0) - c11 (v1.2.1)
+//
+// Each commit is dated one day after the one before it, in the order built.
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Create the repository
+ *
+ * @return {Object} { dir, sha, remove }, where sha maps each commit's name above to its SHA
+ */
+export function createReleaseRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "gren-release-repo-"));
+  // Keep the user's git configuration, such as commit signing, out of the fixture.
+  const baseEnv = { ...process.env, GIT_CONFIG_GLOBAL: "/dev/null", GIT_CONFIG_NOSYSTEM: "1" };
+  const sha = {};
+  let day = 0;
+
+  const git = (args, env = {}) =>
+    execFileSync("git", args, { cwd: dir, encoding: "utf-8", env: { ...baseEnv, ...env } }).trim();
+  const nextDate = () => {
+    day++;
+    const date = new Date(Date.UTC(2020, 0, day)).toISOString();
+
+    return { GIT_AUTHOR_DATE: date, GIT_COMMITTER_DATE: date };
+  };
+  const commit = (name, message) => {
+    fs.writeFileSync(path.join(dir, `${name}.txt`), `${message}\n`);
+    git(["add", "-A"]);
+    git(["commit", "-m", message], nextDate());
+    sha[name] = git(["rev-parse", "HEAD"]);
+  };
+  const merge = (name, branch, message) => {
+    git(["merge", "--no-ff", "-m", message, branch], nextDate());
+    sha[name] = git(["rev-parse", "HEAD"]);
+  };
+
+  git(["init", "-b", "master"]);
+  git(["config", "user.name", "Test"]);
+  git(["config", "user.email", "test@example.com"]);
+
+  commit("c1", "Initial commit");
+  git(["tag", "-a", "v1.0.0", "-m", "v1.0.0"], nextDate());
+  git(["tag", "1.0.0"]);
+  git(["tag", "V1"]);
+  commit("c2", "Add feature A (#1)");
+  git(["tag", "-a", "v1.1.0", "-m", "v1.1.0"], nextDate());
+
+  git(["checkout", "-b", "1.x"]);
+  commit("c3", "Fix bug B (#2)");
+  git(["tag", "v1.1.1"]);
+
+  git(["checkout", "master"]);
+  commit("c4", "Add feature C (#3)");
+  git(["checkout", "-b", "feature"]);
+  commit("c5", "Start feature D");
+  commit("c6", "Finish feature D");
+  git(["checkout", "master"]);
+  merge("m1", "feature", "Merge pull request #4 from feature");
+  commit("c7", "Fix a security issue");
+  commit("c8a", "Tidy docs, part 1");
+  commit("c8b", "Tidy docs, part 2");
+  commit("c9", "Release 1.2.0");
+  git(["branch", "before-sync"]);
+
+  git(["checkout", "1.x"]);
+  merge("m2", "master", "Merge pull request #6 from master");
+  git(["tag", "v1.2.0"]);
+  git(["branch", "after-sync"]);
+
+  git(["checkout", "master"]);
+  commit("c10", "Drop the old API (#7)");
+  git(["tag", "v2.0.0"]);
+
+  git(["checkout", "1.x"]);
+  commit("c11", "Backport fix E (#8)");
+  git(["tag", "v1.2.1"]);
+
+  git(["checkout", "master"]);
+  commit("c12", "Add feature F (#9)");
+
+  return {
+    dir,
+    sha,
+    remove: () => fs.rmSync(dir, { recursive: true, force: true }),
+  };
+}

From 8f4489e75fa16e280e17e6428be707efb882463e Mon Sep 17 00:00:00 2001
From: Chris Barth <chrisjbarth@hotmail.com>
Date: Wed, 16 Sep 2026 09:08:13 -0500
Subject: [PATCH 2/3] Read git dates in UTC whatever git renders

git writes an ISO 8601 date for UTC as either Z or +00:00, depending on
its version, so tests that compared the string failed on a newer git
than the one they were written on. The dates are only ever read as
instants, so normalise them where they are read and the tool behaves
the same on every version of git.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 lib/src/_git.js   | 25 +++++++++++++++++++++----
 test/_git.spec.js |  9 ++++++---
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/lib/src/_git.js b/lib/src/_git.js
index bc42f607..fcb55772 100644
--- a/lib/src/_git.js
+++ b/lib/src/_git.js
@@ -25,6 +25,17 @@ function lines(output) {
   return output ? output.split("\n") : [];
 }
 
+/**
+ * Normalise a date git wrote, which renders UTC as either Z or +00:00 depending on its version
+ *
+ * @param  {string} date
+ *
+ * @return {string} The date in UTC
+ */
+function isoDate(date) {
+  return new Date(date).toISOString();
+}
+
 /**
  * Get the commit each local tag points to. Annotated tags are peeled to their commit.
  *
@@ -42,7 +53,7 @@ function tagCommits() {
     lines(output).map((line) => {
       const [name, object, peeled, date, peeledDate] = line.split("\0");
 
-      return [name, { sha: peeled || object, date: peeledDate || date }];
+      return [name, { sha: peeled || object, date: isoDate(peeledDate || date) }];
     }),
   );
 }
@@ -79,7 +90,13 @@ function releaseCommits(ref, excludeRefs = []) {
   return lines(output).map((line) => {
     const [sha, parents, date, author, subject] = line.split("\0");
 
-    return { sha, parents: parents ? parents.split(" ") : [], date, author, subject };
+    return {
+      sha,
+      parents: parents ? parents.split(" ") : [],
+      date: isoDate(date),
+      author,
+      subject,
+    };
   });
 }
 
@@ -105,10 +122,10 @@ function mergeBranchCommits(sha) {
  *
  * @param  {string} ref A tag, branch or SHA
  *
- * @return {string} The ISO 8601 date
+ * @return {string} The ISO 8601 date, in UTC
  */
 function commitDate(ref) {
-  return git(["log", "-1", "--format=%cI", `${ref}^{commit}`, "--"]);
+  return isoDate(git(["log", "-1", "--format=%cI", `${ref}^{commit}`, "--"]));
 }
 
 /**
diff --git a/test/_git.spec.js b/test/_git.spec.js
index aef79ce0..1ea3ab0d 100644
--- a/test/_git.spec.js
+++ b/test/_git.spec.js
@@ -10,6 +10,9 @@ describe("_git.js", () => {
   let repo;
   let cwd;
 
+  // The fixture dates each commit a day apart, from 1 January 2020.
+  const day = (n) => new Date(Date.UTC(2020, 0, n)).toISOString();
+
   before(() => {
     repo = createReleaseRepo();
     cwd = process.cwd();
@@ -25,7 +28,7 @@ describe("_git.js", () => {
     it("Should peel annotated tags to their commit and its date", () => {
       const tags = git.tagCommits();
 
-      assert.deepEqual(tags.get("v1.0.0"), { sha: repo.sha.c1, date: "2020-01-01T00:00:00+00:00" });
+      assert.deepEqual(tags.get("v1.0.0"), { sha: repo.sha.c1, date: day(1) });
       assert.equal(tags.get("1.0.0").sha, repo.sha.c1, "A lightweight tag");
       assert.equal(tags.get("v1.2.0").sha, repo.sha.m2);
     });
@@ -57,7 +60,7 @@ describe("_git.js", () => {
       assert.deepEqual(commit, {
         sha: repo.sha.c3,
         parents: [repo.sha.c2],
-        date: "2020-01-05T00:00:00+00:00",
+        date: day(5),
         author: "Test",
         subject: "Fix bug B (#2)",
       });
@@ -76,7 +79,7 @@ describe("_git.js", () => {
 
   describe("commitDate", () => {
     it("Should return the committer date of a tag's commit", () => {
-      assert.equal(git.commitDate("v1.0.0"), "2020-01-01T00:00:00+00:00");
+      assert.equal(git.commitDate("v1.0.0"), day(1));
     });
   });
 

From d82f28d497d34868811fb05f9a7cc765ac4e7224 Mon Sep 17 00:00:00 2001
From: Chris Barth <chrisjbarth@hotmail.com>
Date: Wed, 16 Sep 2026 10:22:39 -0500
Subject: [PATCH 3/3] formatting

---
 .markdownlint.json           |   2 +-
 AGENTS.md                    | 156 +++++++++++++++++++++++++++++++++++
 CLAUDE.md                    |   7 ++
 lib/src/Gren.js              |   7 +-
 test/Gren.membership.spec.js |  13 +++
 5 files changed, 183 insertions(+), 2 deletions(-)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.markdownlint.json b/.markdownlint.json
index 6cfbfd99..18e3c716 100644
--- a/.markdownlint.json
+++ b/.markdownlint.json
@@ -1,4 +1,4 @@
 {
-  "MDO13:": false,
+  "MD013": false,
   "MD024": false
 }
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..bf11b347
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,156 @@
+# AGENTS.md
+
+## What this is
+
+`gren` generates release notes and changelogs from a repository's tags, pull requests and
+issues. It is a CLI published to npm, and it is used to produce the `CHANGELOG.md` of
+projects such as `xml-crypto` and `node-saml`.
+
+The changelog is the product. A bug here does not crash anything — it quietly writes a
+wrong history, and nobody notices until someone goes looking for when a fix shipped.
+Silent under-reporting is the failure mode to fear, not an exception.
+
+## Layout
+
+- `lib/gren.js` — the CLI entry point; `lib/gren-*.js` are its commands.
+- `lib/_options.js`, `lib/_examples.js` — the option and example definitions. The README
+  tables are generated from these.
+- `lib/src/Gren.js` — nearly all the behavior: release selection, commit and pull request
+  matching, templating, changelog assembly.
+- `lib/src/_git.js` — the local git reads. Everything that shells out to git lives here.
+- `lib/src/_utils.js`, `_template.js`, `templates.js` — configuration loading, templating
+  and the default templates.
+- `test/*.spec.js` — Mocha specs. `test/fixtures/release-repo.js` builds a throwaway git
+  repository with two release lines, used by the membership and `_git` specs.
+
+## Commands
+
+- `npm test` — `c8 mocha`.
+- `npm run lint` — ESLint plus `prettier --check`.
+- `npm run lint:fix` — rewrites files.
+- `npm run docs` — regenerates the README's option and example tables from `lib/_options.js`
+  and `lib/_examples.js`.
+- `npx markdownlint-cli2 "**/*.md" "#node_modules"` — checks the markdown against
+  `.markdownlint.json`.
+
+Run `npm test && npm run lint` before calling work done, and the markdown check as well if
+you wrote or generated any markdown. If you touched `lib/_options.js`
+or `lib/_examples.js`, run `npm run docs` too and commit what it changes.
+
+`test/Gren.spec.js` skips itself when `GREN_GITHUB_TOKEN` is unset, which is what CI does.
+A green local run with a token is not the same run CI makes — use
+`env -u GREN_GITHUB_TOKEN npx mocha` to see what it will see.
+
+## Hard constraints
+
+### Never hand-edit a generated changelog
+
+A section that comes out wrong is a symptom. Fix the cause — the pull request's title or
+labels, or the project's `gren` configuration — and regenerate. Editing the output leaves
+the next regeneration to undo the correction, and hides the defect that produced it.
+
+This applies to `gren`'s own `CHANGELOG.md`, which `release-it` regenerates on every
+release through the `commits` data source. Commit subjects are the release notes here, so
+the commit message rules in `README.md` are not decoration.
+
+### No repository-specific knowledge in the code
+
+Real repositories have odd histories: an upstream that was renamed, tags in two spellings,
+a security fix with no pull request. Every one of those is a configuration option, never a
+name or SHA in `lib/`. If a project needs something `gren` cannot express, add the option.
+
+### Downstream repositories are out of scope
+
+Changes to a project that consumes `gren` are its maintainer's to make. Generate into a
+scratch file to verify, never over a real `CHANGELOG.md`, and leave no files behind in
+someone else's checkout.
+
+### Prefer an additive minor release
+
+New options and better output are minor. Removing an option, renaming one, or changing
+what an existing option means is major, and worth avoiding rather than versioning around.
+An option that cannot be expressed on a command line — a function, or a nested object such
+as `commitNotes` — belongs in the configuration file only, not in a second format.
+
+### The supported Node floor is real
+
+`engines` in `package.json` is the contract and `.github/workflows/ci.yml` runs the matrix.
+Read both rather than assuming.
+
+### Releasing cleans the working tree
+
+`npm run prerelease` begins with `git clean -xfd`. Anything uncommitted, including new
+files, is gone before the tests run. Commit first.
+
+## Verifying a change
+
+The test suite runs against stubs. Stubs agree with whatever you believed when you wrote
+them, so they cannot tell you that belief was wrong. Before calling a change to the
+generation path done, run it over a repository with real history — many years of tags, merge
+commits, rebase merges and commits with no pull request — writing to a scratch file, and
+diff that against the output from before the change.
+
+Pick a repository that exercises what you changed. Options that only some projects use,
+such as looking for pull requests in another repository, are covered by no other means: if
+nothing you run touches that code path, it is untested however green the suite is.
+
+Say what the diff was. "No diff" and "these three sections changed, because X" are both
+answers. "It should be fine" is not one.
+
+## Tests
+
+Test observable behavior: which releases are generated, what ends up in a section, what is
+reported, and what stops the run. Reach for a private method only where it has a contract
+of its own, such as `_readChangelogSections` or the `_git.js` wrappers.
+
+- **Make the test fail first.** For a bug, reproduce it and watch the test fail for the
+  reported reason before fixing anything. A fix whose test never failed is a guess.
+- **Model the API as it really behaves.** When a stub and GitHub disagree, the suite is
+  worse than useless: it certifies the mistake. If you learn something about a real
+  response — a status code, a field that is sometimes absent — teach the fixture, then
+  watch the existing tests fail.
+- **Don't assert another tool's formatting.** `git` and GitHub are free to render the same
+  value differently between versions. Normalise at the boundary and assert the value, not
+  the spelling it arrived in.
+- Prefer the shared fixture repository over a new one. It already has two release lines, a
+  real cross-line merge, a merge-commit pull request, a rebase-merged one, direct commits
+  and duplicate tag spellings.
+
+## Style
+
+- ESM, Node 24, CommonJS only where a configuration file demands it.
+- `consistent-return` and `prefer-const` are errors, and `no-multiple-empty-lines` allows
+  one. Prettier owns formatting at `printWidth: 100`; don't hand-format.
+- Errors shown to a user are thrown as `chalk.red(...)` strings, not `Error` objects, and
+  say what to do about it. Compare the shallow-clone and missing-tag messages.
+- Warnings that name commits or releases go through `console.warn` in yellow, and give the
+  configuration to paste in where there is one.
+- Markdown, this file included, passes `markdownlint` under the repository's
+  `.markdownlint.json`. That goes for markdown `gren` writes as much as markdown committed
+  here: a changelog that makes a linter complain is a changelog someone has to hand-edit.
+
+## Comments
+
+Code describes itself. Name things well and keep functions small enough that the _what_ and
+the _how_ read from the code, then don't restate them in prose that goes stale the first
+time someone edits the line below.
+
+Comment what the code cannot say: _why_ this way, what breaks if it is done the obvious
+way, which non-obvious constraint is being satisfied. Most comments in `Gren.js` earn their
+place by recording a fact about git or GitHub that the code below depends on — that only a
+rebase merge leaves commits unmatched by `merge_commit_sha`, that 422 means the commit is
+elsewhere. Those are worth keeping. A comment restating the line under it is not.
+
+Don't narrate history. A bug the code no longer has belongs in the commit message, and
+`git blame` leads there.
+
+JSDoc on exported and private methods alike is the house style here and is welcome. Keep it
+to the contract — parameters, what comes back, what it throws — not the implementation.
+
+## Conventions
+
+- Keep changes scoped to the problem. Don't fold unrelated cleanup into a fix.
+- Read the implementation and its tests before changing behavior. Don't infer behavior from
+  a name when the repository can answer the question.
+- Report what actually happened. If a test fails, say so and show the output. If a step was
+  skipped, say which. Confidence that a verification run will pass is not a result.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..d25ecaf4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+The instructions for working in this repository live in @AGENTS.md. Read that file and
+follow it.
+
+This file exists only to point there, so that guidance stays in one place for every tool.
+Add new rules to `AGENTS.md`, not here.
diff --git a/lib/src/Gren.js b/lib/src/Gren.js
index 27b7f44c..d3cf1615 100644
--- a/lib/src/Gren.js
+++ b/lib/src/Gren.js
@@ -314,8 +314,13 @@ class Gren {
   _createChangelog(body) {
     const loaded = utils.task(this, `Creating ${this.options.changelogFilename}`);
     const filePath = process.cwd() + "/" + this.options.changelogFilename;
+    // Each template decides its own spacing, so a heading whose template opens with a blank
+    // line, under a release template that closes with one, leaves two. Markdown reads one and
+    // two the same way; markdownlint does not, and a changelog that trips a linter is one
+    // somebody ends up editing by hand.
+    const content = (this.options.template.changelogTitle + body).replace(/\n{3,}/g, "\n\n");
 
-    fs.writeFileSync(filePath, this.options.template.changelogTitle + body);
+    fs.writeFileSync(filePath, content);
 
     loaded(chalk.green(`Changelog created in ${filePath}`));
   }
diff --git a/test/Gren.membership.spec.js b/test/Gren.membership.spec.js
index e8b18bca..6e44cf2a 100644
--- a/test/Gren.membership.spec.js
+++ b/test/Gren.membership.spec.js
@@ -631,6 +631,19 @@ describe("Gren release membership", () => {
       assert.throws(() => gren._readChangelogSections(), /No releases could be read/);
     });
 
+    it("Should write a changelog without a run of blank lines", () => {
+      // The default templates leave two blank lines under a release heading: the release
+      // template ends with one and the group template opens with another.
+      const gren = createGren({ changelogFilename: "CHANGELOG.md", template: {} });
+
+      gren._createChangelog("## v1.0.0 (2020-01-01)\n\n\n### Bug Fixes\n\n- Fix it\n");
+
+      const written = fs.readFileSync(path.join(repo.dir, "CHANGELOG.md"), "utf-8");
+
+      assert.notMatch(written, /\n{3}/);
+      assert.include(written, "## v1.0.0 (2020-01-01)\n\n### Bug Fixes\n\n- Fix it\n");
+    });
+
     it("Should reject a value that is not a date, tag or commit", async () => {
       const gren = createGren({ frozenBefore: "not-a-ref" });