fix(workflow): insert ### Changed in Keep-a-Changelog order on auto-CHANGELOG (#26)

[cmeans-claude-dev]

Summary

Closes #26. Cascades the validated cmeans/mcp-synology PR #63 fix (squash 8a4df0d, merged 2026-04-26 23:24Z) for the auto-CHANGELOG workflow's subsection-ordering bug. The else-branch in _check_staleness's peer subsection-insertion logic was inserting a new ### Changed block above existing ### Added (or any other subsection that sorts after Changed per Keep-a-Changelog v1.1.0), violating the mandated Added → Changed → Deprecated → Removed → Fixed → Security order.

The bug, when it manifests

Pre-existing layout in ## [Unreleased]	Old workflow output	KaC v1.1.0 says
Empty	Changed	✓
Added only	Changed → Added ❌	Added → Changed
Added + Fixed	(would have been wrong)	Added → Changed → Fixed
Fixed only	(would have been wrong)	Changed → Fixed

Dormant on this repo until v0.1.1 ship: post-PR #25 cascade, the workflow ran on PRs #23 and #24 with both ### Added and ### Changed already populated in ## [Unreleased], so the if-branch (insert under existing ### Changed) fired both times. The next time the buggy else-branch WOULD fire is post-v0.1.1: fresh empty Unreleased, a feature PR adds ### Added, the next weekly Dependabot Monday bump fires the workflow's else-branch.

The fix

Walk forward from ## Unreleased to find either (a) the first subsection that sorts AFTER ### Changed per KaC ordering (### Deprecated, ### Removed, ### Fixed, ### Security), or (b) the next ## release heading. Insert the new ### Changed block immediately before whichever comes first.

Adaptation preserved from our heading-tolerant variant: matcher accepts both ## Unreleased (mcp-synology's form) and ## [Unreleased] (this repo's KaC-bracketed form). Only the else-branch changes (~13 lines); the if-branch, loop guard, idempotency guard, App-token mint, and dependabot[bot] filter are byte-for-byte unchanged.

Verification

Reproduced upstream QA's algorithm-extraction smoke test against six KaC layouts on the cascaded fix locally:

```
A. Empty Unreleased → Changed ✓
B. Added only (the bug case) → Added → Changed ✓
C. Changed already exists → Added → Changed ✓
D. Added + Fixed → Added → Changed → Fixed ✓
E. Fixed only → Changed → Fixed ✓
F. Bracketless heading (## Unreleased) → Added → Changed ✓
ALL PASS
```

All six layouts produce correctly-ordered subsections. Workflow YAML parses via yaml.safe_load.

Test plan

• Algorithm-extraction smoke test on six KaC arrangements — all pass
• Workflow YAML parses cleanly
• Diff scope: .github/workflows/dependabot-changelog.yml (+13/-3) and CHANGELOG.md (+4) only — matches PR claim
• Heading-tolerance adaptation preserved (case F passes with bracketless ## Unreleased)
• Only the else-branch changes — the if-branch (insert under existing ### Changed) is byte-for-byte unchanged from main, verified by inspecting the diff
• CI green on all jobs (lint, typecheck, test 3.11/3.12/3.13, deploy-smoke, codecov)
• Live verification (post-merge, optional): the v1.1 cycle's first feature PR will add ### Added to a fresh ## [Unreleased]; the next Dependabot bump after that triggers the buggy else-branch on the OLD workflow but the fixed path on the new one. If you want belt-and-suspenders, the existing two open Dependabot PRs (none currently — Dependabot is on weekly Monday cycle) could be @dependabot recreate-ed to re-exercise the workflow.

Source

• Upstream fix: cmeans/mcp-synology PR chore(deps): refresh uv.lock transitive pins (2026-05-07) #63 squash 8a4df0d, merged 2026-04-26 23:24Z, validated by upstream QA via the same six-layout smoke test.
• Awareness handoff: add_context id dd3123d2 (the cross-repo finding I posted yesterday for upstream Dev to pick up) — informational entry, the upstream Dev acted on it and shipped the fix in PR chore(deps): refresh uv.lock transitive pins (2026-05-07) #63.
• Verification gate: per the dependabot-pr-hygiene-playbook, fix lands in one repo first + algorithm-extraction smoke test by upstream QA + reproduced locally → cascade approved.

Closes #26

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans-claude-dev]

Rebased on main after v0.1.2 (PR #42) merged. Single conflict in CHANGELOG.md resolved as follows:

The conflict. Both branches inserted text after ## [Unreleased]. PR #41 added a ### Fixed subsection with the #26 cascade bullet (still in flight, lives in [Unreleased]). PR #42 inserted a new ## [0.1.2] - 2026-04-27 released-version section right under [Unreleased].

Resolution. Both stay; no content lost. Final order under [Unreleased] is ### Fixed (the #26 cascade bullet, still in flight), then ## [0.1.2] (released), then ## [0.1.1] (released), then ## [0.1.0]. This matches Keep-a-Changelog ordering (in-flight Unreleased on top, released versions below newest-first).

No substantive change to PR scope. The .github/workflows/dependabot-changelog.yml diff is byte-identical to round 1; CHANGELOG.md diff is byte-identical except the ### Fixed block now sits inside [Unreleased] rather than between [Unreleased] and [0.1.1] (this matches the briefing's documented intent — the bullet was always meant to be Unreleased Fixed).

Verification on rebased branch.

• git diff --stat origin/main...HEAD — same 2 files / +18/-4 as before
• uv run pytest — 71/71 passed
• uv run ruff check src/ tests/ — clean
• uv run ruff format --check src/ tests/ — clean
• uv run mypy src/pypi_winnow_downloads/ — clean

New head: 9320d16 (was 2975d46). Force-pushed with --force-with-lease. Ready for QA label preserved.

[cmeans]

LGTM

[cmeans]

QA round 1 — FAIL (one observation)

Verified the workflow change end-to-end at head 9320d16. Algorithm is correct; one wording observation in the CHANGELOG bullet.

What I verified

• Diff scope: .github/workflows/dependabot-changelog.yml (+13/-3) and CHANGELOG.md (+4) only — matches PR claim.

• If-branch unchanged: git diff f7ff312 9320d16 -- .github/workflows/dependabot-changelog.yml shows exactly one hunk, in the else-branch (lines 169–188 region). The if-branch (changed_idx is not None path), the unreleased_idx matcher (accepts both ## Unreleased and ## [Unreleased]), the loop guard, idempotency check, App-token mint, and dependabot[bot] filter are byte-for-byte unchanged from the parent commit.

• Workflow YAML parses: yaml.safe_load succeeds; jobs: ['changelog'], trigger pull_request_target on [opened, synchronize, reopened].

• Algorithm-extraction smoke test, six PR-claimed layouts (extracted into a standalone qa_smoke.py mirroring the inline Python verbatim):

  Layout	Result	Final order
  A. Empty Unreleased	PASS	### Changed
  B. Added only (the bug case)	PASS	### Added → ### Changed
  C. Changed already exists (if-branch)	PASS	### Added → ### Changed
  D. Added + Fixed	PASS	### Added → ### Changed → ### Fixed
  E. Fixed only	PASS	### Changed → ### Fixed
  F. Bracketless ## Unreleased	PASS	### Added → ### Changed

• Five extra adversarial layouts (not in the PR table — covering the rest of the KaC subsection vocabulary):

  Layout	Result	Final order
  G. Added + Removed	PASS	### Added → ### Changed → ### Removed
  H. Added + Deprecated	PASS	### Added → ### Changed → ### Deprecated
  I. Security only	PASS	### Changed → ### Security
  J. Already-have-Changed + Fixed (if-branch path)	PASS	### Added → ### Changed → ### Fixed
  K. No Unreleased section at all (orthogonal code path)	PASS	fresh ## [Unreleased] with ### Changed

  All four after_changed members (### Deprecated, ### Removed, ### Fixed, ### Security) get walked correctly. Blank-line invariants verified for B/D/E (the new ### Changed heading has a blank line before AND after).

• Repo's own pytest suite at PR head: uv run pytest --cov → 71/71 passed, 100.00% coverage, gate satisfied. ruff check / ruff format --check / mypy clean.

• CI all green at 9320d16: lint, typecheck, test 3.11 / 3.12 / 3.13, deploy-smoke. (Test-plan CI checkbox in the PR body is now ticked.)

• Issue #26 scope: the issue's suggested algorithm — "search forward from unreleased_idx + 1 until either (a) a subsection that should sort after ### Changed per KaC, or (b) the next ## heading" — matches the implementation line-for-line. No scope drift.

Findings

1. (observation, CHANGELOG wording) The new ## [Unreleased] ### Fixed bullet says "Dormant on this repo until #36 release". PR #36 is the stale_threshold_days warning fix that landed during v0.1.1's pre-release cycle, not a release in itself — and PR #38 was actually the last feature-class merge before the v0.1.1 release PR #39. The PR body's narrative gets this right ("Dormant on this repo until v0.1.1 ship"), but the CHANGELOG bullet conflates a PR number with a release version. Future readers of the CHANGELOG will not be able to map #36 release to a release tag without spelunking. Suggest replacing #36 release with v0.1.1 release (or the v0.1.1 release tag) so the dormancy timeline reads cleanly against the project's release history.

Recommendation

Edit the CHANGELOG bullet only — one phrase. Re-apply Ready for QA; I'll re-verify in round 2 (CHANGELOG-only diff, fast turnaround).

Switching label: QA Active → QA Failed.

[cmeans]

Switching label: QA Active → QA Failed. Round 1 — fix is algorithmically correct (11/11 layouts pass, including 5 beyond the PR's six), but one CHANGELOG-wording observation: the bullet says "Dormant on this repo until #36 release" — #36 is a PR number, not a release version. Suggest v0.1.1 release to match the PR body's own narrative.

[cmeans-claude-dev]

QA round 2 — single CHANGELOG wording fix

Addressed the round-1 finding. Replaced #36 release with the v0.1.1 release in the ## [Unreleased] ### Fixed bullet so the dormancy timeline maps cleanly to a release tag instead of a PR number.

Diff:

- Dormant on this repo until #36 release, would have manifested ...
+ Dormant on this repo until the v0.1.1 release, would have manifested ...

Scope: CHANGELOG-only, single phrase, one line changed (+1/-1). No workflow change, no test change. Workflow algorithm at head 837f575 is byte-identical to round-1 head 9320d16 — git diff 9320d16 837f575 -- .github/workflows/dependabot-changelog.yml empty.

Verification:

• uv run pytest — 71/71 passed
• uv run ruff check src/ tests/ — clean
• uv run ruff format --check src/ tests/ — clean
• uv run mypy src/pypi_winnow_downloads/ — clean
• git diff 9320d16 837f575 — single-line CHANGELOG hunk, no other files touched

New head: 837f575 (was 9320d16). Standard additional commit on the branch — no force-push, no rebase. Re-applied Ready for QA.

[cmeans]

LGTM

[cmeans]

QA round 2 — PASS

Round-1 observation resolved in commit 837f575 (CHANGELOG-only diff):

• "Dormant on this repo until #36 release" → "Dormant on this repo until the v0.1.1 release" — exactly the suggested phrasing, dormancy timeline now reads cleanly against the project's release history.

Re-verification

• Workflow YAML byte-identical to round-1 head: diff <(git show 9320d16:.github/workflows/dependabot-changelog.yml) <(git show 837f575:.github/workflows/dependabot-changelog.yml) is empty. Round 1's algorithm verification (11/11 layouts: A–F from the PR table + G/H/I/J/K adversarial extras) carries forward unchanged.
• Diff scope round 1 → round 2: CHANGELOG.md (+1/-1) only — single line edit, no other surface touched.
• CI all green at 837f575: lint, typecheck, test 3.11 / 3.12 / 3.13, deploy-smoke.

Verdict

Zero findings. Awaiting maintainer QA Approved.

[cmeans]

Switching label: QA Active → Ready for QA Signoff. Round 2 PASS — CHANGELOG wording resolved (one-line edit), workflow YAML byte-identical to round 1, CI fully green at 837f575. Awaiting maintainer QA Approved.