CHANGELOG.md

@@ -6,16 +6,6 @@ All notable changes to seismo-relay are documented here.
 
 ## Unreleased
 
-**Blastware Event/FFT-Report parity — the FFT, the USBM compliance chart, and
-the sensor self-check.** Three analyses Blastware derives from event data,
-reverse-engineered against BE12844 (MiniMate Plus) reports and reproduced in
-seismo-relay: the compliance chart and the sensor-check strip now render on
-the event-report PDF, and the FFT reproduces Blastware's FFT Report. All three
-are additive and read from data already on disk — the `.h5` samples and the
-retained raw BW binary — so there is **no `.h5`/DB change, no migration, and no
-backfill**: a report regenerated for an existing event simply gains the new
-panels.
-
 ### Added
 - **Rescue-on-connect for `bridges/ach_server.py`** — `--stop-monitoring`
   (SUB 0x97), `--disable-ach` (SUB 0x2C read → 0x7E write → 0x7F confirm) and
@@ -85,6 +75,16 @@ panels.
 
 ---
 
+### Migration
+
+**None.**  Every change here is additive and reads from data already on disk —
+the `.h5` samples and the retained raw BW binary.  No `.h5`/DB change, no
+schema change, no migration, no backfill, and **no `TOOL_VERSION` bump**: a
+report regenerated for an existing event simply gains the new panels, and the
+`ach_server` rescue flags don't touch the codec.
+
+---
+
 ## v0.30.0 — 2026-09-12
 
 **The series-4 correctness release** — the Thor / Micromate counterpart to

CLAUDE.md

@@ -89,6 +89,36 @@ When new information about the protocol is discovered, please update the instant
 
 ---
 
+## Changelog & release convention
+
+**Write the entry in the same commit as the work, under `## Unreleased`.  Cut
+the version on `dev` in a dedicated release commit.  Never touch the changelog
+at a merge boundary.**
+
+- **Entry goes in with the change**, not at merge or release time — that is the
+  only moment you still know *why*.  Feature branches edit `CHANGELOG.md`
+  directly; the occasional conflict is two appended bullets and is trivial.
+- **No preamble under `## Unreleased`** — just the `### Added` / `### Changed` /
+  `### Fixed` lists.  The themed opening paragraph gets written at release
+  time, when the whole release is visible and can be named honestly.  A theme
+  written when the first item landed is stale by the third.
+- ⚠ **State the operational consequence** on any entry touching the codec, the
+  waveform store, or the DB — **including when it is "none."**  "requires
+  `backfill_sidecars.py` + `backfill_event_shape.py`, ~2 h on the NAS",
+  "`TOOL_VERSION` bumped", "no schema change, no migration".  Silence is
+  ambiguous; "none" is information.  This repo's changelog is how future-you
+  learns whether a deploy costs two hours.
+- **Cutting a release** is its own `chore(release): vX.Y.Z — <theme>` commit on
+  `dev`, renaming `## Unreleased` → `## vX.Y.Z — YYYY-MM-DD` and touching:
+  `CHANGELOG.md`, `pyproject.toml`, the version line in `CLAUDE.md` and
+  `README.md`, and `minimateplus/event_file_io.py` (`TOOL_VERSION`) **when the
+  codec changed** — that constant gates `.h5` regeneration.
+- **`main` carries only released versions.**  No `## Unreleased` section there;
+  it lands via the `dev` → `main` PR.  `main` lagging `dev` by a version is
+  normal.
+
+---
+
 ## Architecture: three-tier conceptual model
 
 seismo-relay is a **suite of cooperating components**, not a single app.