feat(extensions): select exact catalog releases

[Doribelove]

Description

An extension catalog currently keeps only its advertised release. Once that entry advances, users cannot select a still-available older archive from the same trusted catalog. In the #4712 reproduction, a bundle pin for 0.4.12 is rejected after the catalog advances to 0.5.1, although the old ZIP still returns HTTP 200. This PR implements the extension-catalog slice of the maintainer's separate-area plan in #4719; bundle pin resolution remains a separate follow-up.

Versioned entries keep the existing top-level version/URL/digest as the current release and may add historical records under releases. specify extension info <id> --versions shows the available versions, and specify extension add <id> --version 0.4.12 selects the exact record from the winning catalog. Ordinary unqualified installs retain their current behavior. Missing versions do not fall through to lower-priority catalogs; discovery-only catalogs remain non-installable. Historical records need their own URL and SHA-256. The selected record is downloaded directly, then the archive's manifest ID and version are checked before installation. The reference documentation describes the format and this PR's bundle limitation.

Testing

• Tested locally with uv run specify --help.

• Ran existing tests from this working tree's .venv (full results below).

• Tested with a sample project: a localhost catalog advertised 0.5.1 plus a 0.4.12 historical release; extension add --version 0.4.12 requested the old ZIP and installed version 0.4.12.

• Focused extension tests after the discovery-policy regression fix: 127 passed.

• Full test suite before that last, narrowly scoped guard: 8,354 passed, 207 skipped (53 warnings). The final guard and its regression passed the focused run above.

• ruff check and git diff --check: passed.

• A direct markdownlint-cli2 run on the edited reference page reports eight existing violations; the same eight appear on the unmodified main version of that page.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: OpenAI Codex (GPT-6, autonomous mode at the contributor's request; default task settings, with the precise reasoning level not exposed) generated the reproduction, implementation, tests, documentation, and this PR text, then ran the checks listed above. The contributor reports having independently reviewed and tested the patch before marking this PR ready for review. Subsequent agent-generated review responses will also disclose AI use.

[mnriem]

Thanks — this looks like the right first slice of github/spec-kit#4719. The extension-catalog scope is focused and reviewable.

Before approval, could you add tests for the remaining new paths: reject a historical archive with the wrong extension ID or SHA-256 before installation; confirm an unqualified install still selects the advertised current release when releases is present; and cover both a matching and a mismatched packaged version in the bundled exact-version path. The existing tests already cover missing versions, precedence, discovery-only policy, and a wrong archive version.

Posted on behalf of @mnriem by GitHub Copilot (model: GPT-6 Sol, autonomous); comment fully AI-drafted.