#3396 · stacks/logsmith

Symptom

Every repo that uses logsmith to generate CHANGELOG.md produces a file that looks like:

# Changelog
[Compare changes](https://github.com/owner/repo/compare/vA...vB)

### 🚀 Features

- something ([abcdef](https://github.com/owner/repo/commit/abcdef)) _(by user)_

### 🐛 Bug Fixes

- something else ([abcdef](https://github.com/owner/repo/commit/abcdef)) _(by user)_

Notice the heading levels jump directly from # Changelog (h1) to ### 🚀 Features (h3) with no h2 in between. That violates the markdown/heading-increment rule in pickier (and MD001 in markdownlint, and equivalent rules elsewhere) — pickier flags it as an error, which fails the lint job in CI on every release.

Reproduced today in stacksjs/buddy-bot CI:

CHANGELOG.md
   4:1  error  Heading level should not skip from h1 to h3   markdown/heading-increment

I had to band-aid it locally by sed-replacing every ### with ## (buddy-bot@715594e), but that gets undone on the next release because the generator re-emits h3.

Root cause

packages/logsmith/src/config.ts:56:

templates: {
  commitFormat: '- function we(e,n){let t=(r)=>`${n}:${r}`;return{on(r,s,o){e.on(t(r),s,o)},once(r,s){e.once(t(r),s)},off(r,s){e.off(t(r),s)},emit(r,s){e.emit(t(r),s)},emitAsync(r,s){return e.emitAsync(t(r),s)},emitAndCollect(r,s){return e.emitAndCollect(t(r),s)},listenerCount(r){return e.listenerCount(t(r))}}} ([](/commit/)) _(by )_',
  groupFormat: '### ',
  ...
}

The default groupFormat hard-codes h3. Combined with logsmith's own # Changelog h1 at the top of the file and no intermediate h2, the document structure is invalid.

Suggested fix

Change the default to ## :

- groupFormat: '### ',
+ groupFormat: '## ',

That alone resolves the issue. Users who explicitly override groupFormat are unaffected.

Secondary nit (warning, not error)

Pickier also warns:

CHANGELOG.md
   1:1  warn  Headings should be surrounded by blank lines   markdown/blanks-around-headings

…because the generator emits the version compare-link immediately under # Changelog:

# Changelog
[Compare changes](...)

Easy to fix by inserting a blank line after the title. Optional — warnings don't fail CI, but the auto-fixer would clean it up if you ever ran pickier --fix against the generated file.

Blast radius

Every stacksjs repo using logsmith for CHANGELOG generation hits this on next release. Today's count is ~80 repos (the same set covered in stacksjs/rpx#2260's release-script fix).