`downgrade detected` error can dead-end users when project spec_version requires a newer dev build than `pipx upgrade` provides

[tbitcs]

Summary

When a project has been migrated to a newer dev/prerelease spec version, the current downgrade detected remediation can send users into a dead end.

The error tells them to run:

pipx upgrade specsmith

But if the newest released package is still older than the project's spec version, pipx upgrade reports success while leaving the user blocked.

Reproduction from a real project

Date: 2026-07-10
Host: Windows
Project state included:

Project spec_version : 0.21.0.dev787

Installed tool before fix attempt:

specsmith, version 0.20.1

Running commands like specsmith checkpoint --project-dir . failed with:

ERROR: specsmith downgrade detected.
  Project spec_version : 0.21.0.dev787
  Installed specsmith  : 0.20.1 (older)

  Backward migration is not supported.
  Upgrade specsmith first: pipx upgrade specsmith
  Then re-run this command.

But pipx upgrade specsmith still left the machine on 0.20.1 because that was the latest release available through the normal path.

The only working fix was an explicit prerelease install:

pipx install --force specsmith==0.21.0.dev787

Why this is a problem

The current message implies a simple upgrade path exists, but in this state it does not.

That blocks:

• audit
• sync
• checkpoint
• preflight
• any governed workflow in a migrated project

Expected behavior

If a project requires a spec version newer than the installed tool, and that version is not reachable through normal pipx upgrade, specsmith should:

• explain that a prerelease/dev build is required
• print the exact install command if it can determine it
• ideally provide a self-update/bootstrap command that resolves the required version automatically
• distinguish "installed tool is old" from "normal upgrade channel cannot satisfy this project"

Actual behavior

The user is told to run pipx upgrade specsmith, which can be true in principle but false in practice for prerelease-migrated projects.

Suggested fix

• Improve the downgrade error text to mention prerelease/dev version requirements
• Add a command such as specsmith self-update --to-project-version or similar
• Detect when the project spec version is newer than the latest stable release and offer the exact pinned install command
• Document the supported migration/update story for projects that move to dev builds before the stable package is published

This felt like a sharp edge worth filing because it fully blocks governance, and the current remediation message is not enough to recover.