chore: add automated changelog housekeeping workflow (#578)

* chore: add automated changelog housekeeping workflow

Monthly GitHub Actions workflow + Python script that archives older
CHANGELOG.md entries to docs/archive/CHANGELOG-HISTORIC.md and trims
README "Previous Releases" section. Supports --dry-run and validates
no versions are lost during archival.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: prevent changelog housekeeping from truncating README after releases

- Section detection now matches **Previous Releases**: (bold text)
  in addition to # header format — fixes detection for current README
- Section end detection recognizes --- (horizontal rules) and
  **Full version history** footer, not just markdown headers
- Prevents content after Previous Releases (Migration, Documentation,
  Contributing sections) from being lost during trimming

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: address code review findings for changelog housekeeping

- Fix archive boundary: use newest_archived version instead of
  oldest_kept for "Versions vX.Y.Z and earlier" header reference
- Add footer link injection when Previous Releases is the last section
- Remove unused total_after variable
- Pin peter-evans/create-pull-request to SHA for supply-chain security

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Heinrich Krupp <hkr@Mac-mini-von-Heinrich.local>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: 3 people

.github/workflows/changelog-housekeeping.yml

@@ -0,0 +1,71 @@
+name: Changelog Housekeeping
+
+on:
+  schedule:
+    # Runs at 09:00 UTC on the 1st of every month
+    - cron: '0 9 1 * *'
+  workflow_dispatch:  # Allow manual trigger
+
+jobs:
+  housekeeping:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Run changelog housekeeping
+      id: housekeeping
+      run: |
+        python scripts/maintenance/changelog_housekeeping.py 2>&1 | tee /tmp/housekeeping.log
+        EXIT_CODE=${PIPESTATUS[0]}
+
+        # Check if changes were made
+        if git diff --quiet; then
+          echo "changes=false" >> $GITHUB_OUTPUT
+          echo "No changes needed"
+        else
+          echo "changes=true" >> $GITHUB_OUTPUT
+
+          # Extract oldest kept version for branch/commit naming
+          OLDEST=$(grep -oP 'Oldest version in CHANGELOG\.md: v\K[\d.]+' /tmp/housekeeping.log || echo "unknown")
+          echo "oldest_version=$OLDEST" >> $GITHUB_OUTPUT
+        fi
+
+        exit $EXIT_CODE
+
+    - name: Create Pull Request
+      if: steps.housekeeping.outputs.changes == 'true'
+      uses: peter-evans/create-pull-request@67ccf5d5e48bc43b8d67988607b5fdaee1b0f4b8  # v7.0.6
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        commit-message: "chore: archive changelog entries older than v${{ steps.housekeeping.outputs.oldest_version }}"
+        title: "chore: changelog housekeeping — archive older entries"
+        body: |
+          ## Automated Changelog Housekeeping
+
+          This PR was created automatically by the [changelog-housekeeping workflow](../.github/workflows/changelog-housekeeping.yml).
+
+          **What changed:**
+          - Archived older CHANGELOG.md entries to `docs/archive/CHANGELOG-HISTORIC.md`
+          - Kept last 8 versions in CHANGELOG.md
+          - Trimmed README.md "Previous Releases" section (max 7 entries)
+
+          **Validation:** The script verified that no version entries were lost during archival.
+
+          ---
+          *Triggered: ${{ github.event_name == 'schedule' && 'monthly schedule' || 'manual dispatch' }}*
+        branch: chore/changelog-housekeeping
+        delete-branch: true
+        labels: |
+          maintenance
+          documentation
+        assignees: doobidoo