build: add CHANGELOG-structure check to precommit

[bborbe]

Why

Prompt 159 (the work-on fix) once produced a malformed CHANGELOG — a ## Unreleased section inserted above the "All notable changes…" preamble — and it shipped in v0.96.2 because nothing checks CHANGELOG structure. #48 hardened the DoD doc; this adds the mechanical guard so it fails the build instead of relying on the author.

What

• scripts/check-changelog.sh — fails if any ## section (Unreleased or version) appears before the preamble, or the preamble is missing. Mirrors check-versions.sh style; set -euo pipefail-safe (|| true on the greps).
• Makefile — new check-changelog target, wired into the check aggregate that precommit depends on.
• CHANGELOG entry under ## Unreleased (placed correctly — dogfoods the check).

Verified: positive (current CHANGELOG) passes, negative (section above preamble) fails with a clear message, make precommit green.

Provenance

Authored by dark-factory prompt 160; the daemon built it correctly but couldn't land it (container died on flaky integration-test timeouts — unrelated to this change, which touches no Go). Reproduced by hand and run through the normal PR/review flow. Prompt 160 will be marked complete separately.

[ben-s-pull-request-reviewer]

ast-grep is not accessible. The toolchain check fails — following the fail-fast discipline, I'll skip the mechanical funnel (Step 4) and proceed directly to the consolidated report.

---

PR Review: build: add CHANGELOG-structure check to precommit

Target: master ← feature/changelog-structure-check
Files changed: CHANGELOG.md, Makefile, scripts/check-changelog.sh (+44/−1)

---

Step 5: Consolidated Report

Must Fix (Critical)

None.

Should Fix (Important)

None.

Nice to Have (Optional)

• scripts/check-changelog.sh: The new bash script has no unit tests. The plan noted this and it remains unaddressed. Edge cases worth covering: (a) CHANGELOG with missing preamble, (b) ## section placed before the preamble (the very bug this script guards against), (c) a correctly structured CHANGELOG. A simple table-driven test suite using the script's exit code would be appropriate here.

precommit skipped (selector mode) — CI covers lint+test

Step 4 skipped — toolchain gap

ast-grep/sg is not in PATH. The mechanical funnel could not run. Install via:

npm install -g @ast-grep/cli   # or apk add ast-grep in alpine

Container fix: bborbe/maintainer agent/pr-reviewer/Dockerfile commit 1de083f.

---

Step 6: Next Steps

No test-coverage gaps in Go/Python code. For the shell script, consider:

/shellcheck scripts/check-changelog.sh   # validate errexit/pipefail correctness

Step 7: Manual Review

Reviewed all three changed files:

• Makefile: check-changelog target correctly calls @bash scripts/check-changelog.sh. It is added to check (not precommit), which is the intended scope — make check is what gates the build. Wiring is correct.
• scripts/check-changelog.sh: set -euo pipefail is correctly used. The || true guard on the two grep commands is intentional and correct — under set -e, grep returns exit code 1 on no-match, which would otherwise abort the script before the emptiness checks. The comment documents this. The logic for PREAMBLE_LINE and FIRST_SECTION_LINE comparison is sound: only fires when FIRST_SECTION_LINE is non-empty and less than PREAMBLE_LINE. Preamble-only files (no sections yet) pass cleanly.
• CHANGELOG.md: The new ## Unreleased entry is correctly placed below the preamble and above ## v0.96.3, matching the DoD this same PR codifies.

---

{
  "verdict": "approve",
  "summary": "Three-file PR adds a targeted CHANGELOG-structure check script wired into `make check`. The shell script is well-commented, handles `set -euo pipefail` correctly with the `|| true` guard, and the Makefile wiring is clean. One optional improvement: add a simple unit-test suite for the script covering the missing-preamble and section-before-preamble edge cases.",
  "comments": [
    {
      "file": "scripts/check-changelog.sh",
      "line": 1,
      "severity": "nit",
      "message": "Nice to Have: no test suite for this script — consider adding a table-driven test covering missing preamble, section-before-preamble, and valid-CHANGELOG cases"
    }
  ],
  "concerns_addressed": [
    "correctness: grep -n -m1 combined with || true under set -euo pipefail is correct — confirmed: grep exit 1 on no-match would abort without || true",
    "correctness: PREAMBLE_LINE and FIRST_SECTION_LINE emptiness logic is sound — only fires when FIRST_SECTION_LINE is non-empty AND less than PREAMBLE_LINE",
    "tests: scripts/check-changelog.sh has no unit tests — raised as Nice to Have"
  ]
}