release: v2.2.4

.cursor/rules/changelog-alignment.mdc

@@ -0,0 +1,16 @@
+---
+description: Substantive changes must update CHANGELOG.md [Unreleased] in the same work
+alwaysApply: true
+---
+
+# Changelog alignment
+
+When you **modify this repository** in a way that is **not purely trivial** (anything a maintainer or consumer would care about: behavior, public API of scripts, templates, CI, pins, baselines, docs that describe shipped behavior, or release/version flow):
+
+1. **Update `CHANGELOG.md` in the same change** under **`## [Unreleased]`**, using the same categories as the rest of the file (`Added`, `Changed`, `Fixed`, etc.). Summarize what changed and why in plain language; link paths or script names when helpful.
+2. **Keep it accurate**: If you touch **`STANDARDS_VERSION`**, template pins, **`templates/`**, **`scripts/`** consumed by adopters, or **`.github/workflows`**, the changelog entry should reflect that so releases and migration notes stay truthful.
+3. **Do not ship substantive edits without a matching `[Unreleased]` line** unless the user explicitly asked to skip the changelog (rare).
+
+**Exempt (no changelog line required):** typo-only fixes in comments, formatting-only edits with no semantic change, or purely mechanical refactors explicitly scoped as “no changelog” by the user.
+
+If you are **aligning another repo** to these standards, that consumer’s **`CHANGELOG.md`** (or their agreed release notes) should be updated there—not only the standards repo—when your work there is user-visible.

.cursor/rules/changelog-best-practices.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Changelog Best Practices
@@ -139,7 +139,7 @@ Documentation changes should be grouped under the **Documentation** category, no
 
 ## Release Process
 
-Follow **CONTRIBUTING.md §7 (Releasing for maintainers)** (Git Flow: `release/*` branch). Maintainers **must run** **`python3 scripts/prepare_release_bump.py`** `patch`|`minor`|`major` before creating/pushing a `release/*` branch. The script applies the `## [Unreleased]  <!-- release -->` marker (see `.bumpversion.cfg`), runs **bump2version**, **`scripts/fix_changelog_after_bump.py`**, and inserts an empty `## [Unreleased]` for the next cycle. Contributors use plain `## [Unreleased]` until the maintainer runs the script.
+Follow **CONTRIBUTING.md §7 (Releasing for maintainers)** (Git Flow: `release/*` branch). Maintainers **must run** **`python3 scripts/prepare_release_bump.py`** `patch`|`minor`|`major` before creating/pushing a `release/*` branch. The script applies the `## [Unreleased]  <!-- release -->` marker (see `[tool.bumpversion]` in `pyproject.toml`), runs **bump-my-version**, **`scripts/fix_changelog_after_bump.py`**, and inserts an empty `## [Unreleased]` for the next cycle. Contributors use plain `## [Unreleased]` until the maintainer runs the script.
 
 During releases, maintainers also:
 1. Review and consolidate entries moved under the new version

.cursor/rules/comments.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # No Useless Comments

.cursor/rules/commit-message-convention.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Commit Message Convention

.cursor/rules/divide-test-cases.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Divide Test Cases
@@ -87,4 +87,4 @@ def test_invalid_input_then_error(self):
 - Easier test maintenance
 - Better test readability
 - Faster test execution (can run specific scenarios)
-- Easier to debug failures 
+- Easier to debug failures

.cursor/rules/field-name-constants.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 

.cursor/rules/focused-tests.mdc

@@ -1,11 +1,11 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Divide Test Cases

.cursor/rules/git-flow-workflow.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Git Flow Workflow
@@ -22,6 +22,14 @@ This project follows **strict Git Flow**. All changes must follow the branching
 2. Include issue numbers when applicable: `feature/123-add-ogg-support`
 3. Be descriptive: `feature/improve-genre-classification`, not `feature/fix`
 
+## Pull Requests to `develop` (enforced in CI)
+
+Allowed **source branch** prefixes only: `feature/`, `chore/`, `dependabot/`, `release/`.
+
+Classic Git Flow uses **`feature/*`** to integrate features and fixes into `develop`. This repository also allows **`chore/*`** (maintenance, documentation, CI), **`dependabot/*`**, and **`release/*`** when merging release work back into `develop`.
+
+Do **not** use other top-level prefixes (e.g. `docs/`, `fix/`, `refactor/`) for the branch name — CI will fail. Use `feature/<topic>` or `chore/<topic>` instead.
+
 ## Important Rules
 
 - **No direct commits** to `main` or `develop` - all changes must go through Pull Requests

.cursor/rules/issue-description-in-separate-file.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Issue Description in Separate File

.cursor/rules/issue-template-usage.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Issue Template Usage

.cursor/rules/no-useless-comments.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # No Useless Comments
@@ -21,4 +21,4 @@ Bad comments:
 - "Verify Metal branch" (redundant with code)
 - "Check root" (obvious from code)
 - "Get the genre" (redundant with method name)
-- "Loop through items" (obvious from code) 
+- "Loop through items" (obvious from code)

.cursor/rules/one-class-per-file.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # One Class Per File

.cursor/rules/pr-description-in-separate-file.mdc

@@ -1,11 +1,13 @@
 ---
-description: 
-globs: 
+description: PR descriptions must be written to .github/pr-descriptions/ as the primary deliverable
+globs:
 alwaysApply: true
 ---
 # PR Description in Separate File
 
-When creating Pull Requests, always provide the PR description in a separate markdown file located in `.github/pr-descriptions/` directory, rather than writing it directly in the PR body. This directory is git-ignored to keep draft descriptions out of version control.
+When creating Pull Requests **or when the user asks for a PR description** (including phrases like "PR description", "pr desc", "draft PR", or "PR body"), **write the full description to a new markdown file** under `.github/pr-descriptions/` as the primary deliverable. Do not satisfy the request with only chat text: create or update the file, then you may briefly confirm the path in the reply.
+
+When creating the GitHub PR, copy the body from that file and set the PR title from the file header (see **PR Title Required** below). This directory is git-ignored to keep draft descriptions out of version control.
 
 ## File Naming Convention
 
@@ -21,7 +23,7 @@ When a PR description file is provided, **the PR title must be present** in that
 
 ## File Structure
 
-Each PR description file should follow the structure from `.github/pull_request_template.md`:
+Each PR description file should follow the structure from `.github/pr-descriptions/pull_request_template.md`:
 
 - **PR Title** (required) — imperative, concise; e.g. `# PR Description: one-time scripts and migration 0011 fix` or `## PR Title` / `feat(scripts): add one-time DB rename script`
 - Description
@@ -37,11 +39,11 @@ Each PR description file should follow the structure from `.github/pull_request_
 
 ## Usage
 
-1. Create the PR description file in `.github/pr-descriptions/` with a descriptive name
+1. Create the PR description file in `.github/pr-descriptions/` with a descriptive kebab-case name (e.g. match the branch topic)
 2. **Include the PR title** at the top of the file (required when a PR description is provided)
 3. Write the full PR description in that file following the PR template structure
 4. When creating the GitHub PR, set the PR title from the file and copy the body content
-5. The file remains local and git-ignored (not committed to version control)
+5. The file remains local and git-ignored (not committed to version control); see root `.gitignore` under “Draft documents” for any negated paths
 
 ## Benefits
 

.cursor/rules/pre-pr-checklist.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Pre-PR Checklist
@@ -16,10 +16,11 @@ Before submitting a Pull Request, ensure all checks are completed. This checklis
 - ✅ One class per file (see `one-class-per-file.mdc`)
 - ✅ Use field name constants from `Fields.py` files (see `field-name-constants.mdc`)
 - ✅ Private resource filtering includes user in query (see `private-resource-filtering.mdc`)
+- ✅ String enums use `StrEnum`, not `(str, Enum)` (see `.cursor/rules/strenum-string-enums.mdc`, [python-project-standards development baseline](https://github.com/BehindTheMusicTree/python-project-standards/blob/main/docs/development.md) → [string enums](https://github.com/BehindTheMusicTree/python-project-standards/blob/main/docs/string-enums.md), `scripts/check_prefer_strenum.py`, pre-commit / CI `pre-commit` job)
 
 ## Tests
 
-- ✅ All tests pass: `pytest`
+- ✅ All tests pass: `docker compose exec api pytest` (or `pytest` after `python -m pip install -e ".[dev]"` on your machine)
 - ✅ New features have corresponding tests
 - ✅ Bug fixes include regression tests
 - ✅ Tests follow naming convention: `test_{scenario}_then_{expected_result}` (see `test-naming-convention.mdc`)
@@ -37,19 +38,19 @@ Before submitting a Pull Request, ensure all checks are completed. This checklis
 ## Git Hygiene
 
 - ✅ Commit messages follow the commit message convention (see `commit-message-convention.mdc`)
-- ✅ Branch is up to date with target branch (`develop` for features, `main` for hotfixes)
-- ✅ Branch follows naming convention (`feature/`, `chore/`, `hotfix/`, `release/`)
+- ✅ Branch is up to date with target branch (`develop` for `feature/*`, `chore/*`, `dependabot/*`, `release/*`; `main` for `hotfix/*`, `release/*`)
+- ✅ Branch follows naming convention for PRs to `develop`: `feature/`, `chore/`, `dependabot/`, `release/`; for PRs to `main`: `hotfix/`, `release/` (see `git-flow-workflow.mdc` and CONTRIBUTING.md **Branch Protection**)
 - ✅ No accidental commits (large files, secrets, personal configs)
 
 ## Branch Target
 
-- ✅ Feature branches target `develop` branch
+- ✅ `feature/*`, `chore/*`, `dependabot/*`, and `release/*` (when merging into `develop`) target the `develop` branch
 - ✅ Hotfix branches target `main` branch
 - ✅ Release branches target both `main` and `develop` (maintainers only)
 
 ## Quick Pre-PR Command
 
 ```bash
-# Run all checks at once
-pytest && git status
+# Run all checks at once (Docker dev stack)
+docker compose exec api pytest && git status
 ```

.cursor/rules/private-resource-filtering.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Private Resource Filtering

.cursor/rules/pull-request-convention.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Pull Request Title Convention
@@ -29,11 +29,12 @@ PR titles must follow the same format as commit messages: `<type>(<optional-scop
 
 ## Branch Prefixes vs PR Title Types
 
-Branch prefixes (`feature/`, `chore/`, `hotfix/`) differ from PR title types:
+Branch names use Git Flow prefixes; PR titles use Conventional Commits types — they are not the same. Allowed source branches for PRs to `develop` are `feature/`, `chore/`, `dependabot/`, and `release/` only (no `docs/`, `fix/`, etc.); see `git-flow-workflow.mdc`.
 
 - Branch `feature/add-flac-support` → PR title: `feat: add flac support` (use `feat`, not `feature`)
 - Branch `chore/update-dependencies` → PR title: `chore: update dependencies` (use `chore`)
 - Branch `hotfix/critical-bug` → PR title: `fix: critical bug` (use `fix`, not `hotfix`)
+- Dependabot branches keep the `dependabot/` prefix; PR title is usually left as the bot generated or adjusted per review
 
 ## GitHub Auto-Suggested Titles
 
@@ -55,6 +56,6 @@ Branch prefixes (`feature/`, `chore/`, `hotfix/`) differ from PR title types:
 
 ## Target Branch
 
-- Feature branches target `develop`
+- `feature/*`, `chore/*`, `dependabot/*`, and `release/*` (into `develop`) target `develop`
 - Hotfix branches target `main`
 - Release branches target both `main` and `develop` (maintainers only)

.cursor/rules/strenum-string-enums.mdc

@@ -0,0 +1,14 @@
+---
+alwaysApply: true
+---
+
+# String enumerations (`StrEnum`)
+
+For enumerations whose members are **strings** (API keys, serializer field keys, error codes, filter keys, etc.), subclass **`enum.StrEnum`**. Do **not** use **`class Foo(str, Enum)`**.
+
+- Policy and examples: [docs/string-enums.md](https://github.com/BehindTheMusicTree/python-project-standards/blob/main/docs/string-enums.md)
+- Org doc hub: [docs/development.md](https://github.com/BehindTheMusicTree/python-project-standards/blob/main/docs/development.md)
+
+If a call site requires a built-in `str` (e.g. `type(x) is str` instead of `isinstance`), pass **`str(member)`**.
+
+Ruff **UP042** (`replace-str-enum`) enforces this when **`UP`** is in `select` and `target-version` is 3.11+. Optional: **`prefer-strenum`** / `scripts/check_prefer_strenum.py` as an extra guardrail.

.cursor/rules/test-naming-convention.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Test Naming Convention

.cursor/rules/test-structure.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Test Structure
@@ -47,7 +47,7 @@ def test_invalid_input_then_error(self):
     tree_data = [{"name": "", "children": []}]
     response = self._post_genres_tree_import(tree_data)
     self.assertEqual(response.status_code, status.HTTP_400_BAD_REQUEST)  # Bad
-    
+
     # Test duplicate name - should be separate test
     tree_data = [{"name": "Rock", "children": []}, {"name": "Rock", "children": []}]
     response = self._post_genres_tree_import(tree_data)

.cursor/rules/use-assert-not-assertequal.mdc

@@ -1,6 +1,6 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Use assert Instead of assertEqual

.cursor/rules/use-custome-validation-exception.mdc

@@ -1,11 +1,11 @@
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 ---
-description: 
-globs: 
+description:
+globs:
 alwaysApply: true
 ---
 # Use AppValidationException Instead of DRF Validation
@@ -30,7 +30,7 @@ def validate_genre_name(self, name: str, user: User) -> None:
             message="Genre name cannot be empty",
             field_validation_error_code=FieldValidationErrorCode.BLANK
         )
-    
+
     if Genre.objects.filter(user=user, name=name).exists():
         raise AppValidationException(
             field_name=Fields.NAME,
@@ -51,7 +51,7 @@ def validate_genre(self, data: dict, user: User) -> None:
             "message": "Genre cannot be its own parent",
             "code": FieldValidationErrorCode.SELF_REFERENCE
         }
-    
+
     if errors:
         raise AppValidationException(
             field_name=",".join(errors.keys()),