--- name: changelog-rules description: "CHANGELOG doctrine from the owner — the viewer is ENVIRONMENT-AWARE (prod never shows [Unreleased], dev does); hotfixes are a first-class bucket; releases consolidate to FINAL STATE, never the dev play-by-play." metadata: node_type: memory originSessionId: 0b7c5f41-bb34-4ab4-93be-fdb363f5eb40 --- Owner rules for `CHANGELOG.md`. **The doctrine below holds; for where it is codified today, read `CLAUDE.md` + `rules/`.** *Trimmed 2026-07-20: citations to the retired numbering protocol and to `RULES.md` (deleted) were removed. The rules themselves are unchanged.* 1. **The in-app changelog VIEWER must show `[Unreleased]` ONLY on the dev/staging build — NEVER on production.** UPDATED 2026-06-29 with the dev/prod split ([[dev-branch-workflow]]): the **production** site shows ONLY the latest RELEASED version, never `[Unreleased]`. The **dev/staging** build DOES show `[Unreleased]`, so the owner can review unreleased work while testing on his phone. So the viewer must be ENVIRONMENT-AWARE — detect staging vs prod (hostname, or a flag injected by the staging build script) and conditionally render `[Unreleased]`. **`[Unreleased]` always stays in the FILE.** GATE GUARD (self-improving): assert prod-mode never renders `[Unreleased]` AND dev-mode does. *(The pre-split rule was "never show `[Unreleased]` anywhere"; this supersedes it.)* 1b. **HOTFIXES / PATCHES are a first-class concept (owner 2026-06-30).** When fixes land AFTER a version has shipped but are folded INTO that same version (no version bump), they go under a dedicated **`### Hotfix`** category inside that version's release block — NOT `[Unreleased]`, NOT a new version. The changelog logic must DECIDE the right bucket: a change before any release → `[Unreleased]`; a post-release fix folded into the live version → that version's `### Hotfix`; a genuinely new version → its own dated block. The in-app viewer should render `### Hotfix` like the other categories. Add a guard if feasible. 2. **Keep `[Unreleased]` ACTIVELY CURRENT.** Every code change that isn't part of an already-released version gets logged to `[Unreleased]` **as it's made**. When implementing, also sweep that `[Unreleased]` already lists every change made so far — nothing missing. On release, `[Unreleased]` consolidates into the new dated version block. **CHRONOLOGICAL ORDER (owner 2026-06-29):** `[Unreleased]` entries must be in CHRONOLOGICAL order within each category — earliest first, appended as work lands. **Owner caught entries out of order: *"why is suite 95 before 90?"*** Keep the Keep-a-Changelog category grouping (one ### Added / ### Changed / ### Fixed / ### Under the Hood each, standard order), but order the bullets inside each category by when the change actually landed (git log chronology). The in-app viewer renders in the same order; guard where feasible. ⭐ **RELEASE CONSOLIDATION = FINAL-STATE, NOT INCREMENTAL (owner 2026-07-08).** At consolidation, each feature must be described ONCE, by its **FINAL SHIPPED STATE** — not as the incremental dev history. Owner's example: the living core had several separate `[Unreleased]` entries each saying it "now" does X — but the core was ADDED in that very update, so the "now does…" lines read as if it already existed and kept changing. **WRONG.** COLLAPSE all the incremental entries for one feature into a SINGLE cohesive entry describing what the feature IS as shipped. A release block should read as **ONE all-in-one update, not a running dev journal.** Strip "now" phrasing for anything that didn't exist before the update — it's just "Added". This is the one-deduplicated-entry-per-user-visible-change rule applied hard at consolidation: **merge and rewrite, don't concatenate.** ⭐ **FULL CHANGELOG AUDIT — EVERY VERSION READS AS ONE RELEASE (owner 2026-07-08):** audit and rewrite the PROSE of **every past version block** to that same clean "one cohesive release" style — final-state, plain-English, deduplicated, grouped under the standard categories, "now" stripped. The whole file should read as a series of clean releases, **NOT continuous dev development.** ⚠ **CONSTRAINTS — this is a PROSE rewrite ONLY.** PRESERVE the structural markers EXACTLY: version numbers, dates, the header comments, and released blocks' FROZEN values. **Never change a released block's numbers, only its prose.** Keep the `### Hotfix` entries and the category order. Sequence it as a DEDICATED FOLLOW-UP session, never stacked onto a running consolidation session (spec-lock). **README CURRENCY (owner 2026-06-29):** the README was "very outdated" and must be kept current — not just the count/feature-table line bumps, but a **HOLISTIC accuracy check**: whenever a change makes the README's description / feature list / architecture / current-state inaccurate, update those sections **in the same commit**, so the README always describes what the site actually IS — both games, the full feature set, current architecture, current version.