chore(changelog): land entries as per-change fragments in changelog.d/

[Anarchid]

Problem

The changelog policy has a structural conflict generator: every PR inserts prose at the same textual location (the top of ## Unreleased in CHANGELOG.md), so any PR that outlives another merge conflicts there. Concretely: #115's only textual conflict against main is CHANGELOG.md — src/framework.ts and everything else merge cleanly — because #117, #121 and #126 each landed Unreleased entries while it was in review. With the current review cadence this recurs on essentially every long-lived PR. This is the same problem that pushed towncrier, Changesets, and GitLab to per-change fragment files.

Changes

Entries now land as one uniquely-named file per change — changelog.d/<slug>.<breaking|added|changed|fixed>.md, containing the entry's markdown bullets verbatim (slug = PR number or branch name). Distinct files never conflict in git.

• scripts/release-changelog.mjs (the npm version hook) folds pending fragments plus anything filed directly under ## Unreleased into the new ## X.Y.Z — date section (subsections emitted in Breaking/Added/Changed/Fixed order; fragments join an existing matching subsection, including audience-qualified ### Breaking (…) headings), deletes the consumed fragments, and keeps all existing refusals: no/multiple Unreleased headings, duplicate version section, nothing to release. New refusals: unrecognized category suffix and non-bullet fragment content — loud failure instead of silently stranding an entry.
• changelog.yml soft check now passes on a well-formed new fragment or a CHANGELOG.md edit (transition-friendly: in-flight PRs like feat: tune-out — subconscious summaries instead of unsubscribing (#77) #115 that already edited CHANGELOG.md keep passing; no-changelog label escape unchanged). changelog.d/README.md and badly-named fragments do not satisfy it.
• publish.yml is untouched — the tag-time section guard and the github-release mirror job both read the assembled versioned section, which exists at tag time exactly as before because assembly runs pre-tag.
• Migration needs no flag day: direct ## Unreleased edits remain a supported input, merged at release time. The three entries currently sitting under Unreleased on main stay where they are and release normally.
• CONTRIBUTING.md ## Changelog section rewritten, PR-template checkbox updated, changelog.d/README.md documents the format in-place, and this PR dogfoods the scheme with its own fragment (changelog-fragments.changed.md), so the next release exercises the pipeline.
• One deliberate style shift: breaking entries name their audience at the start of the bullet (- **Module authors:** …) instead of in a subsection-heading qualifier; the heading-qualifier form still works via a direct Unreleased edit.

Companion PRs land the same scheme across the ecosystem (same shape as the July policy rollout): antra-tess/membrane#49, anima-research/context-manager#72, anima-research/chronicle#16, anima-research/connectome-host#102. Safe to merge in any order — each repo's scheme is self-contained.

Tests

Release script exercised on a copy through all legs (script output pasted from the runs):

1. Clean cut — 4 fragments (breaking/added/fixed/dogfood-changed) + the 3 real Unreleased entries on main: correct merge into existing subsections, canonical subsection order, continuation lines preserved, fragments deleted, README.md kept. Exit 0.
2. Refuse-duplicate — a '## 0.11.0' section already exists. Exit 1.
3. Refuse-empty — fresh Unreleased, no fragments: nothing to release as 0.12.0 — no fragments in changelog.d/ and no entries under '## Unreleased'. Exit 1.
4. Fragments-only cut (empty Unreleased) — clean section, exit 0.
5. Refuse bad category suffix (oops.md) — exit 1 with naming guidance.
6. Refuse non-bullet fragment — exit 1.
7. Tag guard + github-release awk simulated on the assembled output: guard passes, awk extracts the 32-line section, non-empty.
8. changelog.yml grep logic simulated on six changed-file sets: src+fragment PASS, src+CHANGELOG PASS (legacy), src-alone FAIL, src+changelog.d/README.md-only FAIL, src+badly-named-fragment FAIL, docs-only PASS.

Not verified

A real npm version run end-to-end (next actual release is the live exercise — same status as the existing tag-time guards, which are also still unexercised since the policy landed). The changelog check will run live on this PR itself.

---

• Changelog fragment added — changelog.d/changelog-fragments.changed.md.

🤖 Generated with Claude Code

[Anarchid]

🟠 NEEDS ATTENTION

Reviewer: Codex (GPT-5.6 Sol)

Reviewed head: 018547507c7b7d42c12743195cc492af0c607d3f

Two release-policy defects should be fixed and pinned with automated tests before merge.

1. .github/workflows/changelog.yml:25-30 — deleting somebody else’s fragment satisfies the check.

   changed=$(git diff --name-only "$base...$head")
   # any matching changelog.d path is accepted

   --name-only does not distinguish additions/modifications from deletions. I reproduced a two-commit PR that modified src/example.ts and deleted changelog.d/old.fixed.md; the exact workflow condition printed OK/passed, while git diff --name-status showed D changelog.d/old.fixed.md. That weakens the new policy in precisely the path meant to enforce it and can also remove an unrelated pending entry.

   Filter out deletions (for example with an appropriate --diff-filter) and verify that the accepted fragment exists in the PR head. Preserve rename support by validating the destination path/status rather than falling back to name-only matching.

2. scripts/release-changelog.mjs:50-56 — only the fragment’s first line is validated as a bullet.

   if (!/^[-*] /.test(body)) fail(...)

   The documented format requires one or more bullets with indented continuation lines, but this regex only anchors the beginning of the entire file. A fragment containing - Valid first bullet. followed by unindented top-level prose was accepted, consumed, and emitted into the version section. This disproves the stated “refuse non-bullet fragment” behavior beyond the simplest first-line case.

   Validate every nonblank top-level line: it must begin a bullet, while continuation/nested lines must be indented. Add fixtures for multiple bullets, valid continuations, an invalid first line, and invalid later top-level prose.

Tooling results

• git diff --check origin/main...HEAD: passed.
• npx tsc --noEmit: passed.
• node --import tsx --test test/framework.test.ts: passed.
• Isolated release fold with current Unreleased entries plus the dogfood fragment: passed; category order and fragment deletion were correct.
• Deleted-fragment workflow probe: failed policy expectation; workflow passed a D fragment plus src/ modification.
• Later non-bullet-line release probe: failed policy expectation; malformed fragment was released successfully.
• GitHub Ubuntu, macOS, and changelog checks: passed.

Verdict: the assembler’s normal path is sound, but the check and refusal contract each have a demonstrated hole. Fix those two cases and add a small committed regression harness; no runtime-framework blocker was found.

[Anarchid]

Greptile's review of the membrane companion (antra-tess/membrane#49) found two issues in the shared code, fixed here in 7fc6a14: fragment validation now checks every line (top-level prose or a rogue ## heading refuses the release), and the CI check counts only added fragments (--diff-filter=A), so deleting/renaming one no longer satisfies it.

[Anarchid]

A Codex QA pass on the membrane companion (antra-tess/membrane#49, blocking) found two more shared-code issues, fixed here in d94b4d1: a fragment slug taken verbatim from a fix/foo branch name produced a subdirectory the scanner silently skipped (now fail-closed — anything that isn't README.md or a well-formed fragment aborts the release; docs prescribe / → - slugs), and indented ## headings still slipped past the line check (now a strict grammar: two-space continuations, headings/rules refused at any indent). It also asked for automated coverage: test/release-changelog.test.ts runs the real script in a throwaway directory across 18 cases, including every refusal asserting nothing is modified.

[Anarchid]

Round 2 of the Codex QA pass on membrane (antra-tess/membrane#49) — fixed here in c2fa58a: refusals reported via console.error + process.exit(1) lose their stderr when stderr is a pipe on macOS (async pipes; Linux pipes are sync), so refusals now throw and the entry point sets process.exitCode = 1 and returns normally; and the grammar missed spaced thematic breaks (- - -) and headings as bullet content (- ## x), both now refused (24 regression cases). CI now also runs the suite on both OSes × Node 20/24 (it was ubuntu-only on Node 20, which is why this never surfaced).

[Anarchid]

The macOS × Node 24 leg failed on the first full-suite run on macOS — not the changelog code: 624/628 passed, and the 3 failures are MountWatcher lifecycle re-attach cases in workspace-watcher.test.ts (pass on macOS × Node 20 and on Linux). Filed as #130 with the diagnostics; they look like a genuine Node 24/macOS watcher behaviour difference rather than timing flake (one assertion is that a read-write root gets recreated, and it doesn't). c754ec0 keeps those three Linux-only using the skip pattern the file already uses for a sibling case, so the widened matrix stays meaningful. membrane #49 and context-manager #72 are green on all four legs, which is the macOS verification for the stderr-flush fix.