docs: seed grouped changelog re-arms

BUILDER.md

@@ -84,8 +84,9 @@ triage bug, and the move is to say so on the issue, not to guess.
   one turns out to be wrong or unreachable, say so on the issue and get it
   amended by triage — do not silently ship less than the issue says.
 - Every behavior change adds one line to `CHANGELOG.md` under
-  `## Unreleased` — insert **above** the heading below it, never over it
-  (the monotonic guard's whole reason to exist).
+  `## Unreleased` — in a grouped changelog, append under an existing heading
+  and create one only when the kind is genuinely new; insert **above** the
+  heading below, never over it (the monotonic guard's whole reason to exist).
 - Follow the repo's conventions file and match the code you touch. Tests are
   not optional: the issue's test plan is the floor, not the ceiling.
 - **Scope discipline: the PR does the issue — whole, and nothing else.**

CHANGELOG.md

@@ -6,6 +6,7 @@ so entries say what changed, cite the issue, and stop.
 
 ## Unreleased
 
+- Changelog publication — count entries instead of bytes, refuse dangling grouped headings, and seed grouped re-arms with Added/Changed/Fixed (#98).
 - `labels-reconcile` — grant callers private-repo check reads and warn when an entire PR sweep is blind (#95).
 - `labels-reconcile` — the bootstrap now retires the six GitHub defaults `LABELS.md` publishes as deleted, tolerating both an already-absent label and a refused delete (#93).
 - `issueflow-reconcile` — a triage-authored issue arrival stands down with exit 0 instead of killing the run before the sweep (#91).

CONTRIBUTING.md

@@ -41,8 +41,10 @@ already proven:
 1. **One issue, one PR**, opened as a **draft** while building, with
    `Closes #N` in the body. Drafts are invisible to the reviewer panel on
    purpose. Every behavior change adds one line to `CHANGELOG.md` under
-   `## Unreleased` (insert **above** the heading below — never type over it;
-   the monotonic guard exists because of exactly that edit).
+   `## Unreleased` (in a grouped changelog, append under an existing heading
+   and create one only when the kind is genuinely new; insert **above** the
+   heading below — never type over it; the monotonic guard exists because of
+   exactly that edit).
 2. **When it's ready**: mark ready-for-review and request the whole panel.
 3. **Rounds are answered whole.** Wait until every reviewer has a verdict in,
    then answer the entire round in a **single reply**, push the fixes, and

README.md

@@ -23,11 +23,18 @@ stamps:
    ([lib/version.sh](lib/version.sh)).
 2. **The changelog is stamped *and re-armed* — two edits, not one**
    (box#108). `## Unreleased` becomes `## X.Y.Z — DATE`, and an **empty
-   `## Unreleased` goes back on top**, immediately above it:
+   `## Unreleased` goes back on top**, immediately above it. When the repo
+   groups entries, the ceremony PR seeds its three standing headings:
 
    ```markdown
    ## Unreleased
 
+   ### Added
+
+   ### Changed
+
+   ### Fixed
+
    ## 0.7.1 — 2026-07-19
 
    ### Fixed
@@ -136,15 +143,19 @@ keyed on the tree's version:
 - `-dev` tree → the top section **must** be `## Unreleased`.
 - bare tree (the ceremony PR and its merge) → the top section may be
   `## Unreleased` (re-armed) *or* the stamped section for exactly that
-  version — **and** that version's section must exist and carry prose,
-  because it is the one about to ship (the half-ceremony refusal, rig#67:
-  version bumped, stamp missing — asserted through the very extractor the
-  publisher uses, so the two cannot disagree about what a section is).
+  version — **and** that version's section must exist, carry at least one
+  `-` or `*` entry, and have no `### ` heading without an entry before the
+  next heading or section end. A heading is not an entry. These publication
+  rules do not apply to `Unreleased`: the empty three-heading template is
+  deliberately valid there (the half-ceremony refusal, rig#67: version
+  bumped, stamp missing — asserted through the very extractor the publisher
+  uses, so the two cannot disagree about what a section is).
 
 **The incident**: box#108 / rig#66 — the silent mislanding described
 [above](#what-a-release-is). **Red means** a PR entry has nowhere safe to
-land; **the fix** is to re-arm: add an empty `## Unreleased` above the top
-stamped section.
+land, or a stamped version would publish no entries or a dangling grouped
+heading; **the fix** is to re-arm the top or delete/populate the named
+heading before publishing.
 
 **Do not "simplify" this to "always require `## Unreleased`".** The
 unconditional form is false by construction on the ceremony PR's own tree

docs/CONSUMERS.md

@@ -49,7 +49,18 @@ the machinery at all:
    keeps the repo clear of it entirely. (`package-json` backend: the
    `version` field, same rule.)
 2. **An armed `CHANGELOG.md`**: a preamble plus an empty `## Unreleased`
-   section for the first entries to land under.
+   section for the first entries to land under. If the repo groups entries,
+   seed the shape the ceremony PR will restore at every re-arm:
+
+   ```markdown
+   ## Unreleased
+
+   ### Added
+
+   ### Changed
+
+   ### Fixed
+   ```
 3. **`drills/README.md`** defining what a drill *means* in this repo —
    each repo names its own
    ([the drill doctrine](../README.md#the-drill-doctrine)). Plain
@@ -382,6 +393,11 @@ The portable version of the family's contributor rule — the repo's own
 CONTRIBUTING may sharpen it, but this is the floor the guards assume:
 
 - **Every PR that changes behavior adds one line** under `## Unreleased`.
+- **Grouped changelogs keep three standing headings:** `### Added`,
+  `### Changed`, and `### Fixed`. The ceremony PR's hand-edited re-arm seeds
+  all three; append under one instead of creating a heading at the top
+  anchor. Create `Deprecated`, `Removed`, or `Security` only when a change
+  genuinely needs that rarer kind.
 - **Insert above the heading below — never type over it.** Replacing a
   shipped `## X.Y.Z` heading with your entry deletes that release's
   section, silently; this exact edit is why the
@@ -393,7 +409,8 @@ CONTRIBUTING may sharpen it, but this is the floor the guards assume:
   belong in the PR body, where anyone chasing the reasoning already goes.
 - **Cite the issue or PR** — `(#141)`.
 - **Mark a breaking change** with a leading `BREAKING:`.
-- Group under `### Added` / `### Changed` / `### Fixed` / `### Removed`.
+- Flat changelogs remain flat; the standing-heading rule applies only when a
+  repo already groups its entries.
 
 ## Adopting the agent team flow