Duplicate ID — this entity is also defined in plan/work/WORK-639-marks-are-a-value-shape-metatype-decides-what-they-look-like.md. Only one definition per ID is supported; edits may target the wrong file. Remove the duplicate to resolve.

The changelog generator merges handwritten release notes and collapses changeset detail

scripts/generate-changelog.mjs writes site/content/releases.md as one flat list of changeset bullets per version. This item gives each entry the shape SPEC-160 describes: a summary on top, then the bullets inside {% details %}.

claude/site-changelog-readability-k4p902 View source

Criteria completion

Tracking started Oct 15 — check back for trends.

Relationships

ID:SPEC-161Status:draft

Marketing runes on section: what each needs to compose

ID:SPEC-161Status:draft

Marketing runes on section: what each needs to compose

ID:SPEC-145Status:accepted

Composed runes

ID:SPEC-164Status:draft

Glyphs: a field names a concept, the theme draws it

ID:SPEC-166Status:draft

Value primitives share one contract

ID:WORK-668Status:ready

testimonial is a composition over section, with a codemod for its byline

Priority:mediumComplexity:complexMilestone:v0.44.0

claude/site-changelog-readability-k4p902 current ready

claude/v041-plan-runes-keep-content ready main ready

Oct 15, 03:25 PMf1b561c
Content editedby bjornolofandersson
Oct 15, 01:17 PM4aae7d0
Created (ready)by bjornolofandersson

Acceptance Criteria

A file at releases/notes/v<version>.md is placed verbatim at the top of that version's entry, with its runes left live
A note for a version that has no changelog entry is ignored without failing the script
Without a note, a version whose milestone exists gets the milestone's title in bold and its first paragraph, with preview="drawer" added to each plain {% ref %}
A version with neither a note nor a milestone gets no summary
Every entry's changeset bullets render inside {% details summary="All changes in vX.Y.Z" %}, processed exactly as today
scripts/generate-changelog.test.mjs covers the note, the milestone fallback, the ref rewrite and the no-summary case
site/content/releases.md is regenerated, and the site builds with no new errors

Approach

Milestones are found by reading the name attribute of each file in the plan directory's milestones/ folder (from plan.dir in refrakt.config.json), not by filename. "First paragraph" means the first block after the # heading that is a paragraph, so a milestone that opens with a list or a heading falls through to the next paragraph.

Keep the note and milestone readers as exported functions beside parseChangelog, so the test imports them the same way it does today and importing the module still does not rewrite releases.md.

References

SPEC-160 D1–D4.