Clarify extension catalog semantics for update discovery

[pdfowler]

Problem Statement

Spec Kit extension catalogs currently appear to serve two roles at once:

1. Trust and policy: which extension catalogs or sources a project is allowed to install from, via .specify/extension-catalogs.yml and install_allowed.
2. Release index: which extension versions are considered available for specify extension update.

Those two roles can conflict for org-local catalogs that are intended to bless extension sources rather than approve every individual extension release.

Concrete example:

• An org-local Spec Kit repo has a catalog entry for jira with version: 1.1.0.
• The entry's download_url points at an approved extension source, for example https://github.com/pdfowler/spec-kit-jira/archive/refs/heads/main.zip.
• The extension source's extension.yml on main has version: 1.3.0.
• The local installed registry has jira at version: 1.1.0.

When running:

specify extension update jira

Spec Kit reports the extension is up to date because it compares the installed registry version to the catalog entry version. It does not fetch/read the candidate extension manifest before deciding whether an update exists.

That behavior makes the catalog act like an approved release/version index. That may be the intended governance model, but it is different from using catalogs as an approved source list.

Proposed Solution

Clarify and, if appropriate, support both catalog models:

• Approved source list: the catalog/config blesses where extensions may be installed from, while the extension manifest remains the source of truth for the current installable version.
• Approved version index: the catalog pins or approves a specific extension version, and updates only happen when that catalog version changes.

Possible implementation directions:

• Add a manifest_url or equivalent field to catalog entries so extension update can cheaply fetch the candidate extension.yml before deciding whether an update exists.
• Add an explicit version_policy, such as latest versus pinned, either per catalog or per catalog entry.
• Treat catalog version as display/cache metadata unless the entry is explicitly pinned.
• Warn when a downloaded extension manifest version differs from the catalog entry version.
• Improve specify extension update output when catalog version is equal to installed version but the catalog is being used as the sole update source.

Alternatives Considered

• Keep manually updating org-local catalog version strings for every extension release. This works if the org catalog is meant to be a release approval index, but it adds maintenance overhead and duplicates the extension manifest version.
• Point each project directly at each extension repo's catalog. This reduces version drift, but weakens the usefulness of an org-local catalog as the central policy surface unless the org catalog can bless external catalogs/sources without duplicating release metadata.
• Use specify extension update --dev for local development. This helps local extension authors, but does not address normal catalog-based update behavior for approved remote sources.

Component

Specify CLI (initialization, commands)

AI Agent

Not applicable

Use Cases

1. An organization maintains a Spec Kit project template or internal repo that configures approved extension catalogs for teams.
2. An extension is developed and versioned in its own repository, with extension.yml as the source of truth.
3. The organization wants projects to install and update from approved sources without copying every extension version bump into the org-local catalog.
4. A stricter organization may instead want catalog-pinned versions as an explicit approval gate.

Acceptance Criteria

• Spec Kit documentation clarifies whether catalogs are approved source lists, approved version indexes, or both.
• specify extension update behavior matches that documented model.
• If both models are supported, there is an explicit configuration or catalog field that selects source-based versus pinned-version update discovery.
• Users can tell from CLI output why an extension is considered up to date and which catalog/source made that decision.

Additional Context

The current install_allowed terminology and catalog stack model suggest catalogs can act as a trust boundary. The current update implementation also makes catalog entries the update version source, which is a stronger release approval role. The ambiguity matters most for org-local catalogs that are intended to bless extension sources while letting extension repos own their release versions.