Fix version resolution and detect install conflicts

[ump45nose]

Description

Fixes #333 — the CLI prints vNone / skillware None when a maintainer mixes editable and PyPI installs on the same Python and pip leaves duplicate/orphan skillware distribution metadata.

The root cause is _package_version_str() / get_installed_version() treating corrupt metadata as a valid "None" string and the fallback returning importlib.metadata.version("skillware") verbatim. This PR hardens both, adds conflict detection, and surfaces it via skillware doctor --install plus a startup advisory.

Changes

• skillware/version_policy.py
  • get_installed_version() now treats "", "dev", and literal "None" as invalid (returns None).
  • Added detect_install_conflicts() — flags duplicate distributions, missing Metadata-Version, unparseable versions, orphan .dist-info dirs (no METADATA/RECORD), and editable+wheel coexistence on one interpreter.
  • Added InstallConflict dataclass with code, summary, and Windows/Unix fix commands.
• skillware/cli.py
  • _package_version_str() never returns None or empty — final fallback is "dev".
  • Added emit_install_conflict_advisory() — one dim stderr line on CLI startup when conflicts are detected.
  • Added skillware doctor --install — reports install version + health, lists each conflict with copy-paste Windows/Unix fix commands. Exit 0 = healthy, 1 = conflicts.
• CONTRIBUTING.md — new "Editable vs PyPI on the same Python" subsection documenting one-mode-per-interpreter, uninstall-before-switching, and orphan cleanup.
• CHANGELOG.md — entries under [Unreleased].
• docs/usage/cli.md — documents skillware doctor --install.

Type of Change

• Bug Fix — incorrect runtime or framework behavior
• CLI — skillware/cli.py, docs/usage/cli.md

Checklist (all PRs)

• Linked GitHub issue (Fixes #333)
• Scope matches the issue — no unrelated refactors
• python -m black --check . passes locally
• flake8 . passes locally
• pytest tests/ passes for affected modules (tests/test_cli.py, tests/test_version_policy.py — 87 passed)
• CHANGELOG.md updated under [Unreleased] (user-visible behavior change)
• No skills/ files changed (skill checklist omitted)

Testing

• python -m black --check . → all files unchanged.
• python -m flake8 . → clean.
• python -m pytest tests/test_version_policy.py tests/test_cli.py -q → 87 passed.
• Real editable install on this machine is detected correctly: skillware doctor --install reports the editable+wheel mix and duplicate distribution that actually exist in the local venv (exit 1), and the startup advisory prints when conflicts exist.

Note: the full pytest tests/ / pytest skills/ suites require the [dev,all] extras (google-genai, playwright, PIL, etc.) that are not installed in this local venv; CI installs them via pip install -e ".[dev,all]" and remains authoritative.

AI assistance

This contribution was drafted with AI assistance. Per the repository's Agent Code of Conduct, no AI tool or agent is added to Co-authored-by: trailers.

Related Issues

[rosspeili]

Thanks @ump45nose, good fix approach.

Please comment on #333 and claim the issue first (GFI, unclaimed duplicates clutter the backlog).

Before merge:

1. Rebase on current main (CHANGELOG conflict with feat(creative): add deck_builder skill for deterministic PPTX assembly (#276) #331/feat(cli): add theme subcommand and align help topics with context/ch… #335).
2. skillware config show, install-health block per [Bug]: CLI shows vNone / skillware None when editable and PyPI installs overlap on the same Python #333.
3. scripts/dev_install.ps1 + scripts/dev_install.sh.
4. Unit tests for detect_install_conflicts() (orphan, duplicate, editable+wheel), not just CLI mocks.
5. test_cli_main, assert install advisory runs once on startup.
6. Help ripples: HELP_GROUPS, --help doctor examples, cli.md version-check note; align Windows editable fix with .[dev,all].
7. SKILLWARE_NO_VERSION_CHECK, install advisory respects opt-out or document why not.
8. PR description maps each [Bug]: CLI shows vNone / skillware None when editable and PyPI installs overlap on the same Python #333 acceptance criterion → file/test.

Re-run pytest tests/ after rebase, CI is authoritative. Overall good chunk of work, thanks for transparency with AI usage. We generally highly encourage AI use, as long as you take ownership of commits <3