| name | changelog |
| description | Maintain Mycelium's changelogs. Keeps the top-level CHANGELOG.md (Keep a Changelog 1.1.0, ISO dates, design-phase framing) and each doc's changelog footer in sync with a change, and enforces the append-only status discipline (Draft→Accepted→Superseded, Resolved for notes). Use when finishing a change, moving a doc's status, or cutting a release. |
| when_to_use | Use when staged/committed changes need a changelog entry, when an ADR/RFC/DN status transitions, before opening a PR, or when preparing a release section. |
| argument-hint | [summarize-staged | add <Added|Changed|Deprecated|Removed|Fixed|Security|Open> <entry> | release <version>] |
| allowed-tools | Bash(git diff:*), Bash(git status:*), Bash(git log:*), Read, Grep, Glob, Edit |
changelog
Keep the record honest and append-only.
Top-level CHANGELOG.md
- Format: Keep a Changelog, ISO-8601 dates. The repo
is in the design phase — "changes" are to the docs corpus; versioning starts when the
kernel does. Preserve that framing.
- Add entries under
## [Unreleased] in the right group. Standard groups: Added,
Changed, Deprecated, Removed, Fixed, Security. This repo also uses a custom ### Open
section for tracked-but-unresolved items (e.g. the LH probe, KC-2) — keep it.
- Entry style: terse, past-tense-free imperative-ish bullets that name the doc/path and the
grounding where relevant (mirror existing entries, e.g. "Foundation §5.6 updated: MLIR→LLVM
recorded as the committed AOT path (ADR-007 / RFC-0004)."). Group related edits.
- To draft from staged work: read
git diff --staged (and git status), map each change to a
group, and propose bullets. Don't invent changes that aren't in the diff.
Per-doc changelog footers & status
- Each RFC/ADR/DN carries its own changelog footer and a status. When content changes,
append to that footer and move status only forward:
Draft/Proposed/Preliminary → Accepted → Superseded (design notes: → Resolved).
- Never rewrite an Accepted decision in place — supersede it with a new revision/file and
link the old one forward. Editorial fixes + status transitions are the only in-place edits;
record them.
- Keep
Proven | Empirical | Declared tags honest per VR-5 (per model/op, never aggregate);
a changelog note that upgrades a tag must point to the checked basis that earned it.
Releases (later)
- When versioning starts: move
[Unreleased] items into a dated ## [X.Y.Z] - YYYY-MM-DD
section, add comparison links, and reset [Unreleased].
CHANGELOG.md is periodically swept: older entries move byte-for-byte to an archive (pointer left
at the bottom of the live file) — as of 2026-07-09 the archive lives on the persistent archive
git branch, not an in-tree docs/archive/ dir (clean-snapshot prep; see CLAUDE.md) — those
pre-versioning archived entries are excluded from the first release section when it's cut; the
custom ### Open section rule above still holds.
Checklist before staging the changelog entry
docs/api-index/ in step with source: if any public symbol changed, confirm just docs-index
was run and the updated index is staged before the changelog entry.
Output
Propose the exact diff (which file, which section, which bullets). Confirm cross-references in
new bullets resolve. Note if a status transition implies a supersede that hasn't been written.
