fix(release): keep documentation versions in sync

[lelia]

What changed

• Add scripts/check_release_docs.py to check or rewrite current Socket Basics action and image references in README and docs/**/*.md.
• Run the writer from scripts/prep_release.py, so manual release PRs mechanically update documentation alongside release metadata, uv.lock, and CHANGELOG.md.
• Run the read-only check in the existing python-tests workflow whenever release metadata, release tooling, README, or docs change.
• Add regression coverage that keeps third-party versions (for example checkout and Trivy) independent from the Socket Basics release version.
• Simplify the release-PR checklist around the canonical prep command and required review steps.
• Normalize 73 stale Socket Basics references from 2.0.3 to the current 3.0.0 release.

Root cause

The former .hooks/version-check.py coupled documentation rewriting to an automatic version-bump flow. When that flow was removed in favor of human-authored release PRs, the useful docs-sync behavior disappeared with it. Release metadata advanced to 3.0.0, but in-repo usage examples remained on 2.0.3.

Impact

Future release preparation updates known Socket Basics action tags, image tags, SHA-version comments, and related current-release prose before the release PR is opened. CI reports exact stale file and line locations and prevents a release or docs PR from silently reintroducing version drift. Scanner versions, third-party Action versions, and historical security guidance are not rewritten.

This remains a human-reviewed release flow: the tooling prepares and validates the diff but does not create tags, publish releases, or write across repositories.

Validation

• python3 scripts/check_release_docs.py --check
• Release-doc synchronization dry-run for 3.0.1 — 73 references identified, no files written
• python3 scripts/sync_release_version.py --check
• uv lock --locked
• uv run --no-sync pytest -q — 227 passed
• actionlint .github/workflows/python-tests.yml
• zizmor .github/workflows/python-tests.yml — no findings
• Black and Flake8 on the new checker and tests
• git diff --check

---

Note

Low Risk
Changes are release/docs tooling and example version strings in documentation; no runtime scanner or auth logic is modified.

Overview
Restores mechanical alignment between the canonical release version in pyproject.toml and current-release examples in README.md and docs/**/*.md (action tags, image tags, SHA comments, and related prose). This PR also normalizes 73 stale 2.0.3 references to 3.0.0.

Adds scripts/check_release_docs.py with --check / --write modes. Matching is narrow: only Socket Basics action/image/tag patterns are updated; third-party pins (checkout, Trivy, scanner versions) stay untouched.

scripts/prep_release.py now invokes the docs writer during release prep, alongside existing version metadata and uv.lock sync. The release PR checklist in .github/PULL_REQUEST_TEMPLATE.md is simplified around prep_release.py.

CI (python-tests.yml) runs the read-only docs check when release tooling, README, or docs change, with expanded path filters. Regression tests in tests/test_release_docs.py cover selective rewriting and prep-release integration.

^{Reviewed by Cursor Bugbot for commit 11a3362. Configure here.}