fix: local references, release workflow (#301)

* fix: local references, release workflow

* chore: apply cr comments

.serena/memories/development_standards.md

@@ -44,6 +44,17 @@ make generate-tests         # Create missing tests
 make generate-tests-dry     # Preview test generation
 ```
 
+### Version Management
+
+```bash
+make release [VERSION=vYYYY.MM.DD]  # Create new release (auto-generates version from date if omitted)
+make update-version-refs MAJOR=vYYYY # Update refs to version
+make bump-major-version OLD=vYYYY NEW=vYYYY  # Annual bump
+make check-version-refs              # Verify current refs
+```
+
+See `versioning_system` memory for complete details.
+
 ## Code Style
 
 ### EditorConfig (BLOCKING ERRORS)
@@ -55,18 +66,36 @@ make generate-tests-dry     # Preview test generation
 - **Final Newline**: Required
 - **Trailing Whitespace**: Trimmed
 
-### Shell Scripts (REQUIRED)
+### Shell Scripts (POSIX REQUIRED)
+
+**ALL scripts use POSIX shell** (`#!/bin/sh`) for maximum portability:
 
 ```bash
-#!/usr/bin/env bash
-set -euo pipefail          # MANDATORY
-IFS=$' \t\n'
-trap cleanup EXIT
-trap 'echo "Error at line $LINENO" >&2' ERR
-# Always quote: "$variable", basename -- "$path"
+#!/bin/sh
+set -eu                    # MANDATORY (no pipefail - not POSIX)
+# Quote everything: "$variable", basename -- "$path"
 # Check tools: command -v jq >/dev/null 2>&1
+# Use printf instead of echo -e for portability
 ```
 
+**Why POSIX:**
+
+- Works on Alpine Linux, busybox, minimal containers
+- Faster than bash
+- Maximum compatibility (sh, dash, ash, bash, zsh)
+- CI-friendly, minimal dependencies
+
+**Key Differences from Bash:**
+
+- Use `#!/bin/sh` not `#!/usr/bin/env bash`
+- Use `set -eu` not `set -euo pipefail` (pipefail not POSIX)
+- Use `[ ]` not `[[ ]]`
+- Use `printf` not `echo -e`
+- Use `. file` not `source file`
+- Use `cut`/`grep` for parsing, not here-strings `<<<`
+- Use temp files instead of associative arrays
+- Use `$0` not `$BASH_SOURCE`
+
 ### Python (Ruff)
 
 - **Line Length**: 100 chars
@@ -78,15 +107,68 @@ trap 'echo "Error at line $LINENO" >&2' ERR
 ### YAML/Actions
 
 - **Indent**: 2 spaces
-- **Local Actions**: `uses: ./action-name` (never `../` or `@main`)
+- **Internal Actions (action.yml)**: `ivuorinen/actions/action-name@<SHA>` (SHA-pinned, security)
+- **Test Workflows**: `./action-name` (local reference, runs within repo)
+- **Internal Workflows**: `./action-name` (local reference for sync-labels.yml etc)
 - **External Actions**: SHA-pinned (not `@main`/`@v1`)
 - **Step IDs**: Required when outputs referenced
 - **Permissions**: Minimal scope (contents: read default)
 - **Output Sanitization**: Use `printf`, never `echo` for `$GITHUB_OUTPUT`
 
+## Versioning System
+
+### Internal References (SHA-Pinned)
+
+All `*/action.yml` files use SHA-pinned references for security and reproducibility:
+
+```yaml
+uses: ivuorinen/actions/validate-inputs@7061aafd35a2f21b57653e34f2b634b2a19334a9
+```
+
+**Why SHA-pinned internally:**
+
+- Security: immutable, auditable references
+- Reproducibility: exact version control
+- Portability: works when actions used externally
+- Prevention: no accidental version drift
+
+### Test Workflows (Local References)
+
+Test workflows in `_tests/` use local references:
+
+```yaml
+uses: ./validate-inputs
+```
+
+**Why local in tests:** Tests run within the repo, faster, simpler
+
+### External User References
+
+Users reference with version tags:
+
+```yaml
+uses: ivuorinen/actions/validate-inputs@v2025
+```
+
+### Version Format (CalVer)
+
+- Major: `v2025` (year)
+- Minor: `v2025.10` (year.month)
+- Patch: `v2025.10.18` (year.month.day)
+
+All three tags point to the same commit SHA.
+
+### Creating Releases
+
+```bash
+make release                     # Auto-generates vYYYY.MM.DD from today's date
+make release VERSION=v2025.10.18 # Specific version
+git push origin main --tags --force-with-lease
+```
+
 ## Security Requirements
 
-1. **SHA Pinning**: All external actions use commit SHAs
+1. **SHA Pinning**: All action references use commit SHAs (not moving tags)
 2. **Token Safety**: `${{ github.token }}`, never hardcoded
 3. **Input Validation**: All inputs validated via centralized system
 4. **Output Sanitization**: `printf '%s\n' "$value" >> $GITHUB_OUTPUT`
@@ -104,9 +186,13 @@ trap 'echo "Error at line $LINENO" >&2' ERR
 - Never skip testing after changes
 - Never create files unless absolutely necessary
 - Never nest `${{ }}` in quoted YAML strings (breaks hashFiles)
+- Never use `@main` for internal action references (use SHA-pinned)
+- Never use bash-specific features (scripts must be POSIX sh)
 
 ## Preferred Patterns
 
+- POSIX shell for all scripts (not bash)
+- SHA-pinned internal action references (security)
 - Edit existing files over creating new ones
 - Use centralized validation for all input handling
 - Follow existing conventions in codebase