fix: local references, release workflow (#301)

* fix: local references, release workflow

* chore: apply cr comments

.serena/memories/versioning_system.md

@@ -0,0 +1,219 @@
+# Version System Architecture
+
+## Overview
+
+This repository uses a CalVer-based SHA-pinned versioning system for all internal action references.
+
+## Version Format
+
+### CalVer: vYYYY.MM.DD
+
+- **Major**: `v2025` (year, updated annually)
+- **Minor**: `v2025.10` (year.month)
+- **Patch**: `v2025.10.18` (year.month.day)
+
+Example: Release `v2025.10.18` creates three tags pointing to the same commit:
+
+- `v2025.10.18` (patch - specific release)
+- `v2025.10` (minor - latest October 2025 release)
+- `v2025` (major - latest 2025 release)
+
+## Internal vs External References
+
+### Internal (action.yml files)
+
+- **Format**: `ivuorinen/actions/validate-inputs@<40-char-SHA>`
+- **Purpose**: Security, reproducibility, precise control
+- **Example**: `ivuorinen/actions/validate-inputs@7061aafd35a2f21b57653e34f2b634b2a19334a9`
+
+### External (user consumption)
+
+- **Format**: `ivuorinen/actions/validate-inputs@v2025`
+- **Purpose**: Convenience, always gets latest release
+- **Options**: `@v2025`, `@v2025.10`, or `@v2025.10.18`
+
+### Test Workflows
+
+- **Format**: `uses: ./action-name` (local reference)
+- **Location**: `_tests/integration/workflows/*.yml`
+- **Reason**: Tests run within the actions repo context
+
+### Internal Workflows
+
+- **Format**: `uses: ./sync-labels` (local reference)
+- **Location**: `.github/workflows/sync-labels.yml`
+- **Reason**: Runs within the actions repo, local is sufficient
+
+## Release Process
+
+### Creating a Release
+
+```bash
+# 1. Create release with version tags
+make release VERSION=v2025.10.18
+
+# This automatically:
+#   - Updates all action.yml SHA refs to current HEAD
+#   - Commits the changes
+#   - Creates tags: v2025.10.18, v2025.10, v2025
+#   - All tags point to the same commit SHA
+
+# 2. Push to remote
+git push origin main --tags --force-with-lease
+```
+
+### After Each Release
+
+Tags are force-pushed to ensure `v2025` and `v2025.10` always point to latest:
+
+```bash
+git push origin v2025 --force
+git push origin v2025.10 --force
+git push origin v2025.10.18
+```
+
+Or use `--tags --force-with-lease` to push all at once.
+
+## Makefile Targets
+
+### `make release VERSION=v2025.10.18`
+
+Creates new release with version tags and updates all action references.
+
+### `make update-version-refs MAJOR=v2025`
+
+Updates all action.yml files to reference the SHA of the specified major version tag.
+
+### `make bump-major-version OLD=v2025 NEW=v2026`
+
+Annual version bump - replaces all references from one major version to another.
+
+### `make check-version-refs`
+
+Lists all current SHA-pinned references grouped by SHA. Useful for verification.
+
+## Helper Scripts (\_tools/)
+
+### release.sh
+
+Main release script - validates version, updates refs, creates tags.
+
+### validate-version.sh
+
+Validates CalVer format (vYYYY.MM.DD, vYYYY.MM, vYYYY).
+
+### update-action-refs.sh
+
+Updates all action references to a specific SHA or version tag.
+
+### bump-major-version.sh
+
+Handles annual version bumps with commit creation.
+
+### check-version-refs.sh
+
+Displays current SHA-pinned references with tag information.
+
+### get-action-sha.sh
+
+Retrieves SHA for a specific version tag.
+
+## Action Versioning Action
+
+**Location**: `action-versioning/action.yml`
+
+Automatically checks if major version tag has moved and updates all action references.
+
+**Usage in CI**:
+
+```yaml
+- uses: ./action-versioning
+  with:
+    major-version: v2025
+```
+
+**Outputs**:
+
+- `updated`: true/false
+- `commit-sha`: SHA of created commit (if any)
+- `needs-annual-bump`: true/false (year mismatch)
+
+## CI Workflow
+
+**File**: `.github/workflows/version-maintenance.yml`
+
+**Triggers**:
+
+- Weekly (Monday 9 AM UTC)
+- Manual (workflow_dispatch)
+
+**Actions**:
+
+1. Checks if `v2025` tag has moved
+2. Updates action references if needed
+3. Creates PR with changes
+4. Creates issue if annual bump needed
+
+## Annual Version Bump
+
+**When**: Start of each new year
+
+**Process**:
+
+```bash
+# 1. Create new major version tag
+git tag -a v2026 -m "Major version v2026"
+git push origin v2026
+
+# 2. Bump all references
+make bump-major-version OLD=v2025 NEW=v2026
+
+# 3. Update documentation
+make docs
+
+# 4. Push changes
+git push origin main
+```
+
+## Verification
+
+### Check Current Refs
+
+```bash
+make check-version-refs
+```
+
+### Verify All Refs Match
+
+All action references should point to the same SHA after a release.
+
+### Test External Usage
+
+Create a test repo and use:
+
+```yaml
+uses: ivuorinen/actions/pr-lint@v2025
+```
+
+## Migration from @main
+
+All action.yml files have been migrated from:
+
+- `uses: ./action-name`
+- `uses: ivuorinen/actions/action-name@main`
+
+To:
+
+- `uses: ivuorinen/actions/action-name@<SHA>`
+
+Test workflows still use `./action-name` for local testing.
+
+## Security Considerations
+
+**SHA Pinning**: Prevents supply chain attacks by ensuring exact commit is used.
+
+**Version Tags**: Provide user-friendly references while maintaining security internally.
+
+**Tag Verification**: Always verify tags point to expected commits before force-pushing.
+
+**Annual Review**: Each year requires conscious version bump, preventing accidental drift.