feat: intelligent release notes with Claude Code AI filtering

[mateo-di]

Description

Shortcut

• Story: https://app.shortcut.com/cartoteam/story/XXXXX
• Autolink: [sc-XXXXX]

This PR transforms the CARTO release workflow to use Claude Code for generating intelligent, product-focused release notes that automatically filter out infrastructure and automation changes.

Summary

The release workflow now uses AI-powered commit analysis to ensure release notes only include changes relevant to end-users and product functionality. Infrastructure changes (CI/CD, sync automation, internal docs) are automatically excluded.

Type of change

• Feature

Key Features

🤖 AI-Powered Release Notes

• Uses Claude Sonnet 4.5 to analyze commits
• Generates user-friendly descriptions (not just raw commit messages)
• Automatically categorizes: Features / Bug Fixes / Security / Breaking Changes

🎯 Intelligent Filtering

Automatically excludes:

• ❌ CI/CD workflow changes (.github/workflows/)
• ❌ Upstream sync automation
• ❌ Internal documentation (CARTO_*.md files)
• ❌ Development tooling (Makefile, linting configs)

Automatically includes:

• ✅ LiteLLM core functionality fixes
• ✅ New features and provider support
• ✅ Breaking changes with migration guidance
• ✅ Security-related changes
• ✅ Cherry-picked upstream fixes

🔒 Security Measures

• Actor authorization check (Cartofante, mateo-di only)
• Read-only tools for Claude (Bash, Read, Grep, Glob)
• Rate limited: max 50 turns, 20-min timeout
• No repository write access during notes generation
• Cost: ~$0.50-2 per release

✅ Unchanged Functionality

• Upstream version detection (pyproject.toml)
• Git tagging: `carto-v{version}-{semver}`
• Docker tagging: `carto-stable`, version-specific
• All other release workflow steps

Example Transformation

Before (raw commit):
```
fix: cherry-pick upstream metadata None check [sc-521238]
```

After (Claude analysis):
```
Fixed crash when LiteLLM proxy encounters null metadata in provider responses
```

Excluded (infrastructure):
```
feat: create separate CI fixer workflow with upstream test check
→ Not included in release notes (CI infrastructure change)
```

Acceptance

1. Review workflow changes in `.github/workflows/carto_release.yaml`
2. Verify security-check job is properly configured
3. Confirm Claude Code action has read-only permissions
4. Test workflow with manual trigger (workflow_dispatch)
5. Verify release notes exclude CI/workflow commits
6. Confirm tags and Docker images still work as expected

Basic checklist

• Good PR name
• Shortcut link (update XXXXX)
• Just one issue per PR
• GitHub labels
• Proper status & reviewers
• Tests (manual workflow trigger test needed)
• Documentation (workflow has comprehensive comments)

Testing Plan

To test this PR:

1. Merge to `carto/main`
2. Trigger workflow: Actions → CARTO - Create Release → Run workflow
3. Select bump type (patch/auto)
4. Monitor execution:
   • Security check should pass
   • Claude analyzes commits
   • Release notes generated
5. Verify release notes exclude infrastructure changes
6. Confirm tags and Docker images created correctly

Cost Estimate

• First release: ~$0.50-2 (50 turns with read-only operations)
• Typical release: ~$0.30-1 (fewer turns for smaller changesets)
• Maximum cost: ~$2-3 (timeout ensures hard cap at 20 minutes)

Files Changed

• `.github/workflows/carto_release.yaml` (+183, -40 lines)
  • Added `security-check` job
  • Replaced bash release notes with Claude Code action
  • Enhanced workflow documentation
  • Improved release summary output