Skip to content

CHANGELOG.md: 161 lines of entries sit above the file title, with a duplicate ## [Unreleased] #2138

Description

@seonghobae

What is wrong

CHANGELOG.md on main is structurally malformed. Heading map of the first 200 lines:

  1:### Failed-check finding names the Strix sandbox instead of the gateway
  5:### Strix gate keeps a recovered transient model error from failing a completed scan
  9:### Review sidecar preflight postpones a rate-limited account's candidates ...
 ...   (18 more ### entries)
 70:## [Unreleased]          <-- first Unreleased
155:## 2026-09-02 — Noema single-request gateway ownership
162:# Changelog               <-- the file title, at line 162
170:## [Unreleased]          <-- second Unreleased

Three separate defects, all from the same cause:

  1. The file title # Changelog is at line 162, not line 1. Everything above it is orphaned content with no document root.
  2. There are two ## [Unreleased] sections (lines 70 and 170).
  3. A dated release section (## 2026-09-02, line 155) is stranded between them, above the title, so it reads as newer than releases that are actually newer.

Cause

Successive PRs have each prepended their entry at line 1 rather than under the real ## [Unreleased] at line 170. Each prepend was individually reasonable — the top of the file looked like where recent entries go, because the previous prepend had put one there. Nothing catches it: no test parses CHANGELOG.md's structure. tests/test_agent_review_runtime_quality_consolidation.py and tests/test_pr_review_autofix_nvidia_nim_contract.py reference the file but match prose, not headings.

Why it matters beyond tidiness

The changelog is an acquisition-readiness artifact, not just developer notes. A buyer reading it top-to-bottom sees 161 lines before the document says what it is, then a title, then a second "Unreleased" heading. It also makes every future prepend ambiguous, so the defect keeps growing.

Proposed repair

One dedicated PR, no behavior change:

  1. Move # Changelog (and any preamble) to line 1.
  2. Merge the two ## [Unreleased] sections into one, preserving entry order (the orphaned block at lines 1–69 is newest, so it leads).
  3. Move the ## 2026-09-02 dated section below ## [Unreleased], into date order with the other dated sections.
  4. Add a contract test asserting the invariants that would have caught this: exactly one # heading and it is the first heading in the file; exactly one ## [Unreleased]; it precedes every dated ## section; dated sections are in descending date order.

Step 4 is the part that matters — without it the same drift resumes on the next prepend.

Sequencing

This touches the top of a file that nearly every open PR also touches, so it will conflict with all of them. It should land when the open-PR queue is shallow, and the repair PR should be rebased-and-merged quickly rather than left open. Deliberately not folded into #2137 (orchestrator pin advance) for that reason; #2137's own entry follows the current (wrong) convention so it sits with its peers and this repair stays one coherent change.

Found while placing the changelog entry for #2137.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions