---
name: changelog-scope-vs-commit-range
description: "Release-changelog gating rule — cross-check each bullet's SCOPE against the commit range; a feature touched in-range may predate the release"
metadata: 
  node_type: memory
  type: feedback
  originSessionId: 4a8de2fb-1ebb-4dce-b8fb-c6e4ed060c10
---

When vetting a release CHANGELOG (doyle gates these pre-tag), make sure it COVERS every affected user-facing SURFACE in the commit range, and that each bullet's SCOPE matches its actual delta. NOT one-bullet-per-commit (operator 2026-06-18: "we don't literally need one bullet per commit; just make sure the changelog covers the affected user-facing surfaces"). Two failure modes to catch: (1) a user-facing surface changed in-range but has NO bullet (a miss), and (2) a bullet's claim is broader than its delta — a feature merely TOUCHED in the range may PRE-DATE the release, so name the specific delta, not the whole feature.

**Why:** v0.12.0 shipped with two bullet errors (deployah authored, operator caught one, doyle audit caught both): (1) "Offline agents now appear in the resume-from-history picker" OVERSTATED — the picker (M12) + offline LIVE agents in it (v0.10.0 project-history loader) predate v0.12.0; the real delta was ONLY offline READY/message-listener agents (REQ-READY-AGENT-RESUME ledgering the `spt ready` bind). (2) DROPPED the un-host-psyche-reap bullet (REQ-HAZARD-UNHOST-PSYCHE-REAP) — folded only the brain-restart duplicate-Psyche half (dup-reap), but single-agent stop/signoff detached-Psyche reap was its own user-facing delta.

**How to apply:** (a) `git log vPREV..vNEW --no-merges` to ENUMERATE what changed, then ask "which user-facing SURFACES did this touch?" — ensure each touched surface is covered by a bullet (no surface silently missed) and no bullet claims more than its delta. The commit log is a coverage checklist for surfaces, NOT a 1:1 bullet quota (trivial/internal/refactor commits need no bullet; several commits on one surface = one bullet). (b) For each bullet, verify the claim against CODE not commit-msg (e.g. v0.12.0 F1 relay-exempt confirmed at livehost.rs:524 controllable!=Some(true)). (c) A post-publish changelog/release-notes fix is docs-only — edit CHANGELOG.md on main + `gh release edit vX --repo SaberMage/spt-releases --notes-file`; NO retag/rebuild/re-sign (binaries+signatures untouched). The `## [version]` CHANGELOG.md section becomes the GH release body verbatim (minus the `##` header line) per docs/RELEASE-RUNBOOK.md. Related: [[public-docs-version-not-milestone]].