chore: standardize .version contract with unified parser/writer (lega…

[eva57gr]

…cy + JSON)

[Lightheartdevs]

Review: Standardize .version contract with unified parser/writer

Good intent — centralizing version parsing is the right move. A few things need addressing before this merges.

Blocking

1. python3 hard dependency without fallback. dream-update.sh and migrate-config.sh now exit 1 if python3 is missing. Previously these only needed jq + bash. Adding a mandatory runtime dep that wasn't required before needs either a jq-only fallback path or a clear migration note. On minimal Docker images or fresh installs this could break the update path.

2. No tests for the new shared library. version-file.sh is now a critical contract — it parses both legacy plain-text and JSON formats, handles missing/empty/malformed files, and does semver comparison. The existing test infrastructure (tests/contracts/) should cover this. At minimum: round-trip write/read, legacy format parsing, malformed JSON fallback, semver comparison edge cases.

3. Version source divergence with PR #350. After both merge, version lives in three places with no single source of truth:

   • PR #349: reads/writes .version file (JSON/plain-text)
   • PR #350: reads DREAM_VERSION from .env, falls back to manifest.json

   dream-update.sh check and dream update (from dream-cli) would report different installed versions if .version and .env drift apart. Coordinate with #350 on which is canonical before merging either.

Non-blocking

• Silent Python failures. If the heredoc Python script fails (permission error, etc.), bash functions silently return empty strings. Under set -euo pipefail, empty version strings fed into comparisons could cause unexpected behavior. Surface errors: || { log_error "version parse failed"; return 1; }.
• || true after shift in version_file_upsert_fields — technically violates CLAUDE.md conventions. Use a guard instead.
• Pre-release suffix handling (2.0.0-rc1 → 2.0.0, suffix silently dropped) is reasonable but undocumented.
• cmd_check exit code change (exit 2 for update available) is a behavioral change for any external automation. The help text documents it, but worth a note in PR description.

The version-file abstraction is solid architecture. Just needs tests, the dependency story sorted, and coordination with #350.