Fix base-cli review findings

[codeforester]

Summary

Fixes #7.

This PR addresses the concrete correctness, security, portability, performance, documentation, and adoption findings from the base-cli review.

What changed

• Bound checkout version discovery so unrelated ancestor VERSION files cannot override installed metadata.
• Validate command return values and report invalid non-integer results clearly.
• Enforce owner-only runtime directories (0700) and private JSON files (0600).
• Make base_cli.testing.invoke(cwd=...) expose the fixture directory to real filesystem operations and restore the caller's cwd.
• Centralize YAML dependency loading and private JSON writes.
• Add a Windows history-lock fallback using a private sidecar lock file.
• Add an indexed log-retention path to avoid rediscovering the full run tree on every invocation.
• Enable color automatically on interactive terminals while honoring NO_COLOR and explicit opt-out.
• Add downstream command-protocol schema registration with validation.
• Repair README links, add the missing local-configuration and cache-layout docs, and document Click shell completion.

Compatibility note

The existing IDE schema and Base command-display compatibility remain in place; removing those would be a separate breaking extraction decision.

Validation

• uv run --extra dev pytest -q
• ./tests/validate.sh
• python3 -m compileall -q lib/python tests
• uv run --extra dev python -m build
• git diff --check