ci: add PR title validation workflow (#18)

* ci: add PR title validation workflow

Implement automated enforcement of Conventional Commits specification
for pull request titles using GitHub Actions.

Changes:
- Add pr-title-lint workflow using amannn/action-semantic-pull-request
- Configure validation for standard commit types matching commitlint
- Add sticky comments to guide contributors on invalid titles
- Update CONTRIBUTING.md with PR title format requirements
- Add PR template header with title format examples and guidance

This ensures PR titles follow the same conventions as commits, which is
especially important when using squash merge strategy where the PR title
becomes the final commit message.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* docs: fix markdown linting error in CONTRIBUTING.md

Add 'text' language tag to code fence block to satisfy markdownlint requirements.

Co-authored-by: Damien Storm <[email protected]>

* chore: more linter fixes

---------

Co-authored-by: Claude <[email protected]>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>

Author: 3 people

.github/pull_request_template.md

@@ -1,3 +1,18 @@
+<!--
+📋 PR Title Format: <type>(<optional scope>): <description>
+
+Valid types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
+
+Examples:
+  ✅ feat(auth): add login button to navigation
+  ✅ fix: resolve race condition in async handler
+  ✅ docs: update installation instructions
+  ❌ Add new feature (missing type)
+  ❌ Feat: Add feature (uppercase description)
+
+The PR title will be validated automatically.
+-->
+
 ## Why?
 
 <!-- Summarize the motivation for this change. Reference specs/tasks/issues as needed. -->

.github/workflows/pr-title-lint.yml

@@ -0,0 +1,72 @@
+name: Lint PR Title
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+
+jobs:
+  lint-pr-title:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      statuses: write
+    steps:
+      - uses: amannn/action-semantic-pull-request@v5
+        id: lint_pr_title
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          # Match commitlint config-conventional types
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          # Allow optional scope
+          requireScope: false
+          # Subject should not start with uppercase (matches conventional commits)
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject "{subject}" found in the pull request title "{title}"
+            didn't match the configured pattern. Please ensure that the subject
+            doesn't start with an uppercase character.
+
+      # Add comment when PR title is invalid
+      - uses: marocchino/sticky-pull-request-comment@v2
+        if: always() && (steps.lint_pr_title.outputs.error_message != null)
+        with:
+          header: pr-title-lint-error
+          message: |
+            👋 Thank you for opening this pull request!
+
+            We require PR titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/).
+
+            **Error details:**
+            ```
+            ${{ steps.lint_pr_title.outputs.error_message }}
+            ```
+
+            **Valid format:** `<type>(<optional scope>): <description>`
+
+            **Valid types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+
+            **Examples:**
+            - `feat(auth): add login button to navigation`
+            - `fix: resolve race condition in async handler`
+            - `docs: update installation instructions`
+
+            Please update your PR title and the check will run automatically.
+
+      # Delete comment when PR title is fixed
+      - uses: marocchino/sticky-pull-request-comment@v2
+        if: ${{ steps.lint_pr_title.outputs.error_message == null }}
+        with:
+          header: pr-title-lint-error
+          delete: true

CONTRIBUTING.md

@@ -140,7 +140,7 @@ Semantic versioning and releases are automated in CI using `python-semantic-rele
 ## Pull Requests
 
 - Keep PRs focused and well scoped.
-- Use a conventional title (e.g., `feat: add new prompt`).
+- **PR titles must follow Conventional Commits format** (e.g., `feat: add new feature`). This is enforced by an automated check.
 - PR description template:
 
 ```markdown
@@ -154,6 +154,33 @@ Semantic versioning and releases are automated in CI using `python-semantic-rele
 - Ensure all checks pass (pre-commit) before requesting review.
 - Reference related issues where applicable.
 
+### PR Title Format
+
+PR titles are validated automatically and must follow this format:
+
+```text
+<type>(<optional scope>): <description>
+```
+
+**Valid types:** `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
+
+**Examples:**
+
+- `feat(auth): add login button to navigation`
+- `fix: resolve race condition in async handler`
+- `docs: update installation instructions`
+- `chore: bump dependencies and run pre-commit`
+
+The description should:
+
+- Start with a lowercase letter
+- Be concise and descriptive
+- Use imperative mood (e.g., "add" not "added" or "adds")
+
+**Breaking changes:** Add `!` after the type (e.g., `feat!: drop Python 3.10 support`)
+
+If the automated check fails, update your PR title and it will re-run automatically.
+
 ## Issue Templates
 
 Use the GitHub issue templates under `.github/ISSUE_TEMPLATE/` for bug reports, feature requests, and questions. These templates prompt for summary, context/repro, and related prompt/workflow information.