Adopts changelog fragments

.claude/wurk.json

@@ -78,7 +78,8 @@
   },
 
   "changelog": {
-    "mode": "none"
+    "mode": "fragments",
+    "dir": "changelog.d"
   },
 
   "release": null

.claude/wurk/commit.md

@@ -3,20 +3,24 @@
 Additional required steps. Adds only - see
 `~/.claude/skills/wurk:commit/SKILL.md` for everything this does not repeat.
 
-## Changelog: none
-
-`changelog.mode` is `none` in the manifest, so there is no fragment step and
-nothing to ask about.
-
-This is a decision, not an omission. While the package is `0.1.0-dev` with no
-users and no public API, every entry would say some version of "the package
-started existing" - and 0.1.0's changelog is better written in one pass from
-git history than assembled from a pile of per-bead fragments, which is only
-possible while there is no prior release to diff against.
-
-sui-n0r switches this to `fragments` when the first release is on the horizon,
-and says why fragments rather than a single `CHANGELOG.md`. Do not start
-writing changelog entries before then; do not let `none` outlive the release.
+## Changelog: fragments
+
+`changelog.mode` is `fragments` with `changelog.dir` at `changelog.d`
+(sui-6vy, adopted fleet-wide 2026-08-21 so the convention exists before
+parallel work starts, not after the first conflict). A user-facing change
+gets one file per bead under `changelog.d/`; the rules - when a fragment is
+and is not warranted, format, naming - live in `changelog.d/README.md`.
+
+While the package is `0.1.0-dev` with no users and no public API, most
+changes still warrant no fragment: apply the README test (could someone who
+only ever calls the public API tell the difference?) and expect the answer
+to usually be no. 0.1.0's own changelog section is still written in one
+pass from git history at release time (sui-n0r), which is only possible
+while there is no prior release to diff against; fragments cover what lands
+after that pass makes sense.
+
+`CHANGELOG.md` itself does not exist yet and is never edited outside a
+release.
 
 ## Version bump: none
 

.gitignore

@@ -22,6 +22,10 @@ statifier_ui-*.tar
 # Temporary files, for example, from tests.
 /tmp/
 
+# Changelog fragments are tracked. A global gitignore rule for `*.d` (C/C++
+# dependency files) matches this directory name and would otherwise hide them.
+!changelog.d/
+
 # Beads / Dolt files (added by bd init)
 .dolt/
 *.db

changelog.d/README.md

@@ -0,0 +1,93 @@
+# Changelog fragments
+
+Changelog entries for unreleased work live here as one file per issue, not as
+edits to `CHANGELOG.md`. At release the fragments are assembled into a single
+version section and deleted.
+
+## Why fragments
+
+Parallel work happens in one worktree per issue, so several branches are
+usually open at once. If each branch appended to the `## [Unreleased]` block
+at the top of `CHANGELOG.md`, every branch would touch the same few lines of
+the same file and nearly every pull request would conflict with every other
+one.
+
+A fragment is named after its issue, so no two branches ever write the same
+file and the conflict cannot happen.
+
+## When a change needs a fragment
+
+The changelog serves **people who use the library**. Repo history is git's
+job, and work tracking is beads' job. Neither belongs here.
+
+Write a fragment for:
+
+- a public API addition, change, or removal
+- a change in observable behavior
+- a change to a published contract - the fixtures layout or the trace wire
+  format - that a consumer could notice
+- a bug fix a user could have noticed
+- anything breaking
+
+Do **not** write a fragment for:
+
+- test harness or internal test-support changes
+- documentation, ADRs, or plans
+- internal refactors with no visible effect
+- quality gate, CI, or agent tooling changes
+
+If you are unsure, ask whether someone who only ever calls the public API
+could tell the difference. If not, skip it.
+
+## Format
+
+One file per issue, named for the beads issue ID:
+
+    changelog.d/sui-abc.md
+
+Contents are the Keep a Changelog section heading followed by the entry:
+
+```markdown
+### Changed
+
+- `StatifierUI.Trace.Json.decode/1` returns `{:ok, message}` instead of a
+  bare message.
+```
+
+Rules:
+
+- Use only the standard headings: `Added`, `Changed`, `Deprecated`, `Removed`,
+  `Fixed`, `Security`.
+- One line per change, present tense, describing the effect on the user.
+- No nested bullets. Detail belongs in the pull request and the commit body; a
+  changelog line that needs sub-points is really several changes or one that
+  is over-explained.
+- One file may carry more than one heading if an issue genuinely spans them.
+- For a breaking change, say what to do about it, not just what broke.
+
+Good:
+
+```markdown
+### Removed
+
+- Drops `StatifierUI.Fixtures.validate/1`. Layout errors now arrive as
+  `{:error, reason}` from `StatifierUI.Fixtures.load/1`.
+```
+
+Too much:
+
+```markdown
+### Removed
+
+- **Validator removal**: The validator function has been removed
+  - **Rationale**: Validation is now part of loading
+  - **Impact**: Callers must handle `{:error, reason}`
+  - **Migration**: Replace calls to ...
+```
+
+## At release
+
+Assemble the fragments into a new version section in `CHANGELOG.md`, grouped
+by heading and ordered `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`,
+`Security`. Delete the fragments in the same commit that cuts the release,
+and tag it.