@heroiclands/package-build 22.4.1 → 22.4.3

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @heroiclands/package-build
 
+## 22.4.3
+
+### Patch Changes
+
+`@heroiclands/package-build/changelog` writes each changeset's summary into `CHANGELOG.md` as its
+
+own block, so three pull requests each touching compendium content leave three separate
+
+`**Compendiums**` blocks instead of one. `changelog group` rewrites the newest release section in
+
+place: every block sharing one label is merged into a single block, bullets kept in their original
+
+order with an exact duplicate kept once, and the merged blocks are ordered by a new
+
+`changelog.labels` configuration key — the unlabelled lead paragraph first, then every declared
+
+label in order, then any undeclared label last with a warning naming it. `changelog check` warns on
+
+a label absent from a declared `changelog.labels` too, so a drifted spelling is caught before a
+
+release ships it.
+
+`@heroiclands/package-build/changelog` is a Changesets changelog generator
+
+whose `getReleaseLine` renders a changeset's summary as a block, verbatim —
+
+no bullet, no indentation, separated from its neighbours by one blank line —
+
+and whose `getDependencyReleaseLine` writes nothing. Point
+
+`.changeset/config.json` at it
+
+(`"changelog": "@heroiclands/package-build/changelog"`) to stop every release
+
+note from carrying a commit-hash prefix.
+
+**A new `changelog group` command folds a release's changeset blocks together by their bold label.**
+
+**A shipped changelog generator writes a release note without a commit hash.**
+
+## 22.4.2
+
+### Patch Changes
+
+- 8dedb23: **A module embedding HM3 spells, invocations or psionics compiles.** A being's
+  embedded `spell`, `invocation` or `psionic` reference that names no shortcode
+  template and no `data.icon` of its own now takes that subtype's own default
+  art — the icon HM3 itself assigns a freshly created item of that kind —
+  instead of the build refusing the actor outright.
+- 54109cf: **A module embedding HârnMaster 3 weapons compiles.** A being's `(type,
+  shortcode)` reference into HM3's one-to-many `weapongear` row resolves when
+  its `type` names one of the row's own subtypes — `weapongear` or
+  `missilegear` — instead of being refused as ambiguous.
+
 ## 22.4.1
 
 ### Patch Changes

package/CONTENT.md

@@ -2830,12 +2830,12 @@ zero differences, so only "which file was read" separates the outcomes.
 Releasing is not a command anyone runs. It is a consequence of merging, in two
 steps, and each step is visible while it is pending.
 
-**Every pull request declares its bump.** Run `npx changeset` and pick
-major/minor/patch; the summary you write becomes the changelog entry and the
-release note. If the change ships nothing a consumer can see, say so explicitly
-with `npx changeset add --empty`. CI's **Changeset declared** job fails a pull
-request that declares neither — `npm run changeset:check` is the same check,
-locally.
+**A pull request declares its bump when a consumer will notice.** Run
+`npx changeset` and pick major/minor/patch; the summary you write becomes the
+changelog entry and the release note. Nothing a consumer meets means no
+changeset at all — CI carries no gate demanding one. What CI does check is the
+quality of a changeset that exists: `node bin/package-build.mjs changelog check`
+lints every pending one against the rules a changeset is held to.
 
 **Merging to `main` opens a Version Packages pull request** carrying the version
 bump and the rewritten `CHANGELOG.md`. That pull request _is_ the pending

package/README.md

@@ -638,12 +638,12 @@ the first import.
 Releasing is not a command anyone runs. It is a consequence of merging, in two
 steps, and each step is visible while it is pending.
 
-**Every pull request declares its bump.** Run `npx changeset` and pick
-major/minor/patch; the summary you write becomes the changelog entry and the
-release note. If the change ships nothing a consumer can see, say so explicitly
-with `npx changeset add --empty`. CI's **Changeset declared** job fails a pull
-request that declares neither — `npm run changeset:check` is the same check,
-locally.
+**A pull request declares its bump when a consumer will notice.** Run
+`npx changeset` and pick major/minor/patch; the summary you write becomes the
+changelog entry and the release note. Nothing a consumer meets means no
+changeset at all — CI carries no gate demanding one. What CI does check is the
+quality of a changeset that exists: `node bin/package-build.mjs changelog check`
+lints every pending one against the rules a changeset is held to.
 
 **Merging to `main` opens a Version Packages pull request** carrying the version
 bump and the rewritten `CHANGELOG.md`. That pull request _is_ the pending

package/bin/package-build.mjs

@@ -54,6 +54,7 @@
  *   npx package-build lang coverage [--unused]
  *   npx package-build lang hardcoded
  *   npx package-build changelog check [--release] [paths..]
+ *   npx package-build changelog group [paths..]
  *   npx package-build bundle check
  *   npx package-build release
  *   npx package-build deploy <stage>
@@ -82,7 +83,7 @@ import { loadPackageBuildConfig } from "../config.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments } from "../content-config.mjs";
-import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
+import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
 import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
@@ -90,6 +91,7 @@ import { validateLangSource } from "../lang.mjs";
 import { checkLabelRegistry } from "../labels.mjs";
 import { lintYaml } from "../engine/yaml-lint.mjs";
 import { lintChangesetText, lintReleaseText } from "../engine/changelog-lint.mjs";
+import { groupChangelogText } from "../engine/changelog-group.mjs";
 import { bumpDependencies } from "../engine/dependency-bump.mjs";
 import {
     analyzeCoverage,
@@ -779,41 +781,53 @@ function yamlCommand() {
 }
 
 /**
- * `changelog check` — lint release prose against the rules a changeset is
- * actually held to (`check` is the only action).
- *
- * A changeset answers one question — who notices, and what do they see — and
- * nothing enforced it, so a pull-request description pasted into one ships
- * verbatim as a release note. Default reads every pending changeset;
- * `--release` reads the first `## <version>` section of `CHANGELOG.md`
- * instead, for the **Version Packages** branch a merge to `main` opens.
+ * `changelog check` / `changelog group` — release-prose checks, and folding
+ * a release's changeset blocks together by their bold label.
+ *
+ * `check` answers one question a changeset otherwise goes unheld to — who
+ * notices, and what do they see — so a pull-request description pasted into
+ * one does not ship verbatim as a release note. Default reads every pending
+ * changeset; `--release` reads the first `## <version>` section of
+ * `CHANGELOG.md` instead, for the **Version Packages** branch a merge to
+ * `main` opens.
+ *
+ * `group` rewrites that same first `## <version>` section in place: every
+ * changeset in it writes its own `**Compendiums**` block, and nothing merges
+ * the three a release with three compendium fixes ends up with. It reads
+ * `changelog.labels` for the vocabulary and display order, when the
+ * repository declares one.
  *
  * @returns {object} The yargs command module.
  */
 function changelogCommand() {
     return {
         command: "changelog <action> [paths..]",
-        describe: "Release-prose checks",
+        describe: "Release-prose checks, and folding a release's blocks by label",
         builder: (y) =>
             y
                 .positional("action", {
-                    choices: ["check"],
-                    describe: "check: lint pending changesets, or a release section",
+                    choices: ["check", "group"],
+                    describe:
+                        "check: lint pending changesets, or a release section. " +
+                        "group: fold a release section's blocks together by label",
                 })
                 .positional("paths", {
                     describe:
-                        "Files to check. Defaults to `.changeset/*.md` (config.json and " +
-                        "README.md excluded), or `CHANGELOG.md` with --release.",
+                        "Files to act on. Defaults to `.changeset/*.md` (config.json and " +
+                        "README.md excluded) for check, or `CHANGELOG.md` for check --release " +
+                        "and for group.",
                     type: "string",
                 })
                 .option("release", {
                     type: "boolean",
                     default: false,
                     describe:
-                        "Check the first `## <version>` section of CHANGELOG.md instead of " +
-                        "pending changesets",
+                        "check only: check the first `## <version>` section of CHANGELOG.md " +
+                        "instead of pending changesets",
                 }),
-        handler: handler(async (args) => changelogCheck(args)),
+        handler: handler(async (args) =>
+            args.action === "group" ? changelogGroup(args) : changelogCheck(args),
+        ),
     };
 }
 
@@ -835,19 +849,35 @@ function changelogFiles(args) {
     );
 }
 
+/**
+ * `changelog.labels`, when this repository declares a configuration — `null`
+ * otherwise, so `check` and `group` both work in a tree with no
+ * `package-build.config.yaml` at all, exactly as `check` already does for
+ * pending changesets with no configuration to read.
+ *
+ * @returns {readonly string[]|null}
+ */
+function loadChangelogLabels() {
+    const found = resolveConfigFile();
+    if (!found.path) return null;
+    return loadPackConfig().changelog.labels;
+}
+
 /**
  * Run `changelog check` over every resolved file and report the result.
  *
  * @param {object} args - Parsed CLI arguments.
  */
 function changelogCheck(args) {
+    const labels = loadChangelogLabels();
     const files = changelogFiles(args);
     let errors = 0;
     let total = 0;
     for (const file of files) {
         if (!fs.existsSync(file)) die(`changelog check: ${file} does not exist.`);
         const text = fs.readFileSync(file, "utf8");
-        const { findings } = args.release ? lintReleaseText(text) : lintChangesetText(text);
+        const { findings } =
+            args.release ? lintReleaseText(text, { labels }) : lintChangesetText(text, { labels });
         errors += reportFindings(findings, { file });
         total += findings.length;
     }
@@ -858,6 +888,26 @@ function changelogCheck(args) {
     if (errors) process.exitCode = 1;
 }
 
+/**
+ * Run `changelog group` over every resolved file, writing each back in place.
+ *
+ * @param {object} args - Parsed CLI arguments.
+ */
+function changelogGroup(args) {
+    const labels = loadChangelogLabels();
+    const files = args.paths?.length ? args.paths : ["CHANGELOG.md"];
+    let warnings = 0;
+    for (const file of files) {
+        if (!fs.existsSync(file)) die(`changelog group: ${file} does not exist.`);
+        const original = fs.readFileSync(file, "utf8");
+        const { text, findings } = groupChangelogText(original, { labels });
+        reportFindings(findings, { file });
+        warnings += findings.length;
+        if (text !== original) fs.writeFileSync(file, text, "utf8");
+    }
+    console.log(`package-build: ${files.length} file(s) grouped · ${warnings} warning(s)`);
+}
+
 /**
  * `labels check` — do the machine registry and the documented table agree?
  *

package/changelog.cjs

@@ -0,0 +1,55 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The Changesets changelog generator every HeroicLands repository configures
+ * as `"changelog": "@heroiclands/package-build/changelog"`.
+ *
+ * Every built-in generator writes a commit hash into the release line
+ * whenever it knows the commit, which it always does in this org's
+ * squash-merge workflow — `@changesets/cli/changelog` writes `- <hash>: `,
+ * and `@changesets/changelog-git` adds a link on top of it. A commit hash is
+ * a commit-log artefact, not something the person installing the package
+ * needs, and the writing conventions keep tracker and commit references out
+ * of the tree. `getReleaseLine` writes the changeset's summary and nothing
+ * else; `getDependencyReleaseLine` writes nothing, because none of these
+ * packages narrate an internal dependency bump.
+ *
+ * Changesets loads a changelog generator with `require`, so this is
+ * CommonJS in a package that is otherwise `"type": "module"`.
+ *
+ * @module
+ */
+
+/**
+ * @param {{summary: string}} changeset - The pending changeset. Only
+ *   `summary` is read; a known `commit` is deliberately ignored.
+ * @returns {string} The summary rendered as a block, verbatim — no leading
+ *   `- `, no indentation of the following lines — wrapped in a single
+ *   newline on each side so Changesets' own joiner (which counts, rather
+ *   than reads, the newlines bracketing a release line) always separates
+ *   this block from its neighbours by one blank line.
+ */
+function getReleaseLine(changeset) {
+    return `\n${changeset.summary}\n`;
+}
+
+/**
+ * @returns {string} Always empty — these packages have no internal
+ *   dependency bumps to narrate.
+ */
+function getDependencyReleaseLine() {
+    return "";
+}
+
+module.exports = { getReleaseLine, getDependencyReleaseLine };

package/content-config.mjs

@@ -756,10 +756,12 @@ const CONFIG_KEYS = [
     "requiresSystem",
     "packageBuild",
     "publish",
+    "changelog",
 ];
 const SYSTEM_KEYS = ["manifest", "compatibility"];
 const COMPATIBILITY_KEYS = ["minimum", "verified"];
 const DOCS_KEYS = ["itemFields"];
+const CHANGELOG_KEYS = ["labels"];
 const SITE_KEYS = [
     "base",
     "assets",
@@ -1458,6 +1460,37 @@ function normalizeDocs(value) {
     });
 }
 
+/**
+ * `changelog.labels` — the vocabulary and display order `changelog check`
+ * and `changelog group` read a release block's bold label against.
+ *
+ * Optional: a repository that groups nothing declares none, and `group`
+ * falls back to ordering every label by first appearance. Declared, it is a
+ * list of non-empty strings with no duplicate — a repeated label could never
+ * be told apart from a genuine drift (`Compendiums` twice would silently
+ * swallow the `Character data` beside `Characters` the list exists to catch).
+ *
+ * @param {unknown} value - The configured value, or `undefined`.
+ * @returns {Readonly<{labels: readonly string[]|null}>}
+ */
+function normalizeChangelog(value) {
+    if (value === undefined) return Object.freeze({ labels: null });
+    if (!isPlainObject(value)) fail("changelog", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(input, CHANGELOG_KEYS, "changelog.");
+    if (input.labels === undefined) return Object.freeze({ labels: null });
+    if (!Array.isArray(input.labels)) fail("changelog.labels", "must be an array");
+    const labels = input.labels.map((label, index) =>
+        requireNonEmptyString(label, `changelog.labels[${index}]`),
+    );
+    const seen = new Set();
+    for (const label of labels) {
+        if (seen.has(label)) fail("changelog.labels", `declares \`${label}\` more than once`);
+        seen.add(label);
+    }
+    return Object.freeze({ labels: Object.freeze(labels) });
+}
+
 /**
  * The asset host the website resolves a pathname against.
  *
@@ -2758,5 +2791,6 @@ export function defineConfig(config) {
         requiresSystem,
         packageBuild: normalizePackageBuild(input.packageBuild),
         publish: normalizePublish(input.publish),
+        changelog: normalizeChangelog(input.changelog),
     });
 }

package/docs/api.md

@@ -1555,6 +1555,22 @@ console.log(VISIBLE_ATTRIBUTES);
 | `findHardcodedText`        | `findHardcodedText(source, { allow = [] } = {})` | `TemplateFinding[]`                                                 | finding every user-visible literal a template leaves untranslated; `allow` is the explicit, reasoned escape hatch for a literal that is deliberately not a key        |
 | `findTemplateSyntaxErrors` | `findTemplateSyntaxErrors(source)`               | `TemplateFinding[]` — one finding when it does not parse, else none | checking whether Handlebars can parse a template at all, without needing any helper it calls to exist                                                                 |
 
+## `./changelog`
+
+The Changesets changelog generator, loaded with `require` — a CommonJS module in a package that is otherwise `"type": "module"`. Every HeroicLands repository sets `"changelog": "@heroiclands/package-build/changelog"` in its `.changeset/config.json`, because every built-in generator writes a commit hash into the release line whenever it knows the commit, which it always does in this org's squash-merge workflow, and a commit hash is a commit-log artefact rather than something the person installing the package needs.
+
+`getReleaseLine` renders a changeset's summary as a block, verbatim — no leading `- `, no indentation of the following lines — so a summary that opens with a paragraph, a bold label, or its own bullet list lands in `CHANGELOG.md` exactly as written. It wraps the summary in a single newline on each side, which costs nothing in the rendered file — Changesets' own joiner trims a release line's edges and only counts the newlines it finds there — but guarantees the block is separated from its neighbours, heading or sibling entry alike, by one blank line.
+
+```json
+// .changeset/config.json
+{ "changelog": "@heroiclands/package-build/changelog" }
+```
+
+| Export                     | Signature                                                                  | Returns                                                                         | Use it when                                                                                        |
+| -------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `getReleaseLine`           | `getReleaseLine(changeset, type, changelogOpts)`                           | `string` — the summary, verbatim, separated from its neighbours by a blank line | writing one changeset's release line with no commit-hash prefix and no bullet                      |
+| `getDependencyReleaseLine` | `getDependencyReleaseLine(changesets, dependenciesUpdated, changelogOpts)` | `string` — always `""`                                                          | satisfying the `ChangelogFunctions` interface; these packages narrate no internal dependency bumps |
+
 ## `./package.json`
 
 Not a JavaScript module — this subpath entry exists so tooling (bundlers, `import.meta.resolve`, a script reading the installed version) can resolve the package's own `package.json` through Node's package-exports resolution instead of reaching outside the declared export map.

package/docs/commands.md

@@ -646,8 +646,11 @@ from the heading rule, since neither is authored.
 A token that reads as code — `camelCase()`, a `path/with/slashes.ext`,
 `SCREAMING_SNAKE` — outside any code span is a warning, not a failure: a
 user-facing note sometimes needs one (`Compendium.hm3.items.Item.<id>`), but
-rarely. Every other finding is an error. Reads the files given, or resolves
-its own defaults; writes nothing.
+rarely. A block's bold label absent from a declared `changelog.labels` is
+also a warning — the drift `**Character data**` beside `**Characters**`
+produces — and checks nothing when the repository declares no
+`changelog.labels`. Every other finding is an error. Reads the files given,
+or resolves its own defaults; writes nothing.
 
 **OPTIONS**
 
@@ -678,6 +681,71 @@ package-build: 1 file(s) checked · 1 error(s) · 0 warning(s)
 
 [Diagnostics](diagnostics.md).
 
+### `package-build changelog group`
+
+**NAME**
+
+Fold a release section's changeset blocks together by their bold label
+(`group` is a sibling of `check`, not one of its actions).
+
+**SYNOPSIS**
+
+```
+package-build changelog group [paths..]
+```
+
+**DESCRIPTION**
+
+`@heroiclands/package-build/changelog` writes each changeset's summary into
+`CHANGELOG.md` as its own block, verbatim, under `### <Bump> Changes` — one
+per changeset, in whatever order Changesets read the files. Three pull
+requests each touching compendium content each write their own
+`**Compendiums**` block, and nothing merges them: the release reads as three
+scattered entries instead of one.
+
+`group` rewrites the first `## <version>` section of `CHANGELOG.md` in
+place. Within each `### <Bump> Changes` body, every block sharing one bold
+label is merged into a single block for that label — its bullets kept in
+the order they were originally written, an exact-duplicate bullet kept
+once — and the merged blocks are reordered: the unlabelled lead paragraph a
+changeset writes with no category first, then every label
+[`changelog.labels`](configuration.md#changelog) declares, in the order
+given, then any label absent from that list last, in the order it first
+appeared — each reported as a warning naming it. With no `changelog.labels`
+declared, every group instead keeps the order its label first appeared in,
+lead paragraph first, and nothing is reported as unknown. Every earlier
+release section is untouched, byte for byte. Running `group` on its own
+output is a no-op.
+
+**OPTIONS**
+
+| Positional | Type      | Default        | Description                         |
+| ---------- | --------- | -------------- | ----------------------------------- |
+| `paths`    | string(s) | `CHANGELOG.md` | Files to group, rewritten in place. |
+
+**EXIT STATUS**
+
+1 if a named file does not exist. 0 otherwise — an undeclared label is a
+warning, never a failure.
+
+**EXAMPLES**
+
+```
+$ package-build changelog group
+package-build: 1 file(s) grouped · 0 warning(s)
+```
+
+```
+$ package-build changelog group
+CHANGELOG.md:12: warning: changelog-group/unknown-label "Scenery" is not declared in `changelog.labels` — filed last, in order of first appearance
+package-build: 1 file(s) grouped · 1 warning(s)
+```
+
+**SEE ALSO**
+
+[`changelog check`](#package-build-changelog-check),
+[`changelog.labels`](configuration.md#changelog).
+
 ### `package-build bundle check`
 
 **NAME**

package/docs/configuration.md

@@ -48,7 +48,7 @@ around its own evaluation.
 
 ### Quick reference
 
-20 top-level keys. `rootDir` is not one of them — a data configuration never
+21 top-level keys. `rootDir` is not one of them — a data configuration never
 writes it — and is documented under [Derived values](#derived-values) instead,
 alongside `foundryPackage`, `homepage`, `author` and `itemBuilders`, whose
 data-configuration behaviour is also derivation rather than ordinary
@@ -76,10 +76,11 @@ authoring.
 | [`requiresSystem`](#requiressystem)         | string                                                                     | no; refused in a `documentation` package                                                           | `null`                                      |
 | [`packageBuild`](#the-packagebuild-section) | object                                                                     | no                                                                                                 | `{}`                                        |
 | [`publish`](#publish)                       | object                                                                     | no; **required**, with `site: content`, in a `documentation` package                               | `{site: "homepage", address: {prefix: ""}}` |
+| [`changelog`](#changelog)                   | object                                                                     | no                                                                                                 | `{labels: null}`                            |
 
 Any key outside this list is refused:
 
-> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish). ``
+> `` `<key>` is not a recognized option (expected one of: rootDir, contentPackage, foundryPackage, homepage, author, packageKind, stats, itemBuilders, paths, skipDirectories, icons, packs, docs, site, pdf, compatibility, relationships, systems, requiresSystem, packageBuild, publish, changelog). ``
 
 (`rootDir` appears in that list because it is a key `defineConfig` itself
 accepts — an `.mjs` configuration authors it directly. A YAML configuration
@@ -289,7 +290,7 @@ Unlike the first three, authoring `itemBuilders` is not an error — it is
 
 ---
 
-## The 20 keys
+## The 21 keys
 
 ### `contentPackage`
 
@@ -1334,6 +1335,45 @@ Any other key under `publish.address` is refused:
 
 > ``package-build config: `publish.address.<key>` is not a recognized option (expected one of: prefix).``
 
+### `changelog`
+
+**Type:** object · **Optional**, default `{labels: null}`.
+
+`changelog check` and `changelog group` both read a release block's bold
+label — `**Compendiums**` — against `changelog.labels`: the vocabulary and
+display order a repository declares for the categories its changesets group
+under. Declaring none is ordinary — a repository that writes plain,
+unlabelled changesets needs nothing here.
+
+| Key                | Type     | Required | Default |
+| ------------------ | -------- | -------- | ------- |
+| `changelog.labels` | string[] | no       | `null`  |
+
+> ``package-build config: `changelog` must be a mapping.``
+
+> ``package-build config: `changelog.<key>` is not a recognized option (expected one of: labels).``
+
+> ``package-build config: `changelog.labels` must be an array.``
+
+> ``package-build config: `changelog.labels[<n>]` must be a non-empty string.``
+
+A repeated label is refused rather than silently deduplicated — it could
+never be told apart from the drift the list exists to catch (`Compendiums`
+written twice swallows a genuine `Character data` beside `Characters`):
+
+> ``package-build config: `changelog.labels` declares `Compendiums` more than once.``
+
+With `changelog.labels` declared, `changelog group` orders a release
+section's blocks by that list — the unlabelled lead paragraph first, then
+every declared label in the order given, then any undeclared label last, in
+the order it first appears, each reported as a warning naming it. With no
+`changelog.labels` declared, `group` orders every block by first
+appearance, lead paragraph first, and warns about nothing. `changelog check`
+warns on a block whose label is not in a declared `changelog.labels`; with
+none declared, it checks nothing. See
+[`package-build changelog check`](commands.md#package-build-changelog-check)
+and [`package-build changelog group`](commands.md#package-build-changelog-group).
+
 ---
 
 ## The `packageBuild` section

package/docs/project-setup.md

@@ -82,12 +82,13 @@ carries no hook files of its own and cannot drift from the others. `|| true` so
 that an install outside a git checkout — a Docker build, a CI cache step —
 does not fail on it.
 
-Three hooks arrive with it, each with its own switch, read with git's normal
+Four hooks arrive with it, each with its own switch, read with git's normal
 precedence: a plain `git config` sets one clone, `--global` sets a machine.
 
 | Hook                             | What it does                                                    | Key                                  | Default |
 | -------------------------------- | --------------------------------------------------------------- | ------------------------------------ | ------- |
 | `pre-commit`, `pre-merge-commit` | Refuse a commit on a protected branch.                          | `hooks.allowCommitOnMain` (inverted) | on      |
+| `pre-commit`                     | Lint any `.changeset/*.md` the commit stages.                   | `hooks.changelogCheck`               | on      |
 | `commit-msg`                     | Refuse AI attribution in a commit message.                      | `hooks.noAttribution`                | on      |
 | `pre-push`                       | Run this repository's own Build & Test workflow in a container. | `hooks.prePushCi`                    | off     |
 
@@ -130,19 +131,20 @@ anything to remove.
 
 ### `lint:*` — the checks, one per question
 
-Six checks, each answering one question and blind to what the others see. They
-are separate scripts rather than one because a failing chain stops at its first
-failure, and knowing _which_ question failed is most of the diagnosis.
+Seven checks, each answering one question and blind to what the others see.
+They are separate scripts rather than one because a failing chain stops at its
+first failure, and knowing _which_ question failed is most of the diagnosis.
 
 ```json
-"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:labels",
+"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:labels lint:changelog",
 "lint:format": "content-build format",
 "lint:markdown": "content-build markdown",
 "lint:markdown:fix": "content-build markdown --fix",
 "lint:addresses": "content-build lint",
 "lint:content-links": "content-build links",
 "lint:lang": "package-build lang check",
-"lint:labels": "package-build labels check"
+"lint:labels": "package-build labels check",
+"lint:changelog": "package-build changelog check"
 ```
 
 - **`lint:format`** — is every file formatted to the shared Prettier options?
@@ -165,6 +167,10 @@ failure, and knowing _which_ question failed is most of the diagnosis.
 - **`lint:labels`** — do `.github/labels.yml` and §3 of
   `.github/ISSUE_REPORTING.md` still list the same labels? Neither derives from
   the other, so nothing else notices when they drift.
+- **`lint:changelog`** — does every pending `.changeset/*.md` read like a
+  release note rather than a pasted pull-request description? Passes
+  trivially when nothing is pending: no pull request is required to carry a
+  changeset, only to write one that reads well when it does.
 
 `run-s` comes from `npm-run-all`, a devDependency. It runs scripts in sequence
 and stops at the first failure, which is what makes a named chain readable.
@@ -227,16 +233,19 @@ reads better with one and a CI workflow reads better with the other.
 
 ```json
 "changeset": "changeset",
-"changeset:check": "changeset status --since=origin/main",
 "changeset:version": "changeset version && npm install --package-lock-only"
 ```
 
-`changeset` adds one. `changeset:check` reports what is pending against `main`,
-which is what a CI job gates on so that a behaviour change cannot merge without
-declaring its bump. `changeset:version` consumes the pending changesets, writes
-`CHANGELOG.md` and bumps `package.json` — and the `npm install --package-lock-only`
-after it is what keeps `package-lock.json`'s recorded version in step, since
-changesets does not touch the lockfile.
+`changeset` adds one, written only when a consumer will notice the change —
+nothing gates a pull request on carrying one. `changeset:version` consumes the
+pending changesets, writes `CHANGELOG.md` and bumps `package.json` — and the
+`npm install --package-lock-only` after it is what keeps `package-lock.json`'s
+recorded version in step, since changesets does not touch the lockfile.
+
+What a pending changeset is held to is quality, not existence: `lint:changelog`
+and the `pre-commit` hook `prepare` installs both run
+`package-build changelog check` against it, in CI and at commit time
+respectively, and both pass trivially when there is none.
 
 ### The site scripts