[Feature]: Record structured provenance for installed presets and extensions

[nicolehaugen]

Problem Statement

ExtensionRegistry and PresetRegistry currently record a hard-coded "source": "local" value for every installation, including packages installed from downloaded catalog archives. This loses the distinction between local-directory, catalog, and bundled installations.

The affected install methods are:

• ExtensionManager.install_from_directory
• PresetManager.install_from_directory

Both methods currently write "source": "local" when adding registry metadata. Catalog installations eventually use these same methods after downloading and extracting an archive, so catalog-installed packages are indistinguishable from packages installed from a local filesystem path.

There is no git-install pathway today. However, the registry metadata needs a forward-compatible shape so future git installation can be represented without another schema redesign.

Existing registry data may contain:

1. No source field, from older records.
2. "source": "local", including records created by current installs.
3. "source": "catalog", a documented legacy value that does not identify the catalog.

Proposed Solution

1. Define a shared internal SourceInfo schema used by both registries:

{
  "kind": "catalog | local | builtin | git",
  "catalog": "<catalog-name>",
  "path": "<absolute-path>",
  "url": "<git-url>",
  "ref": "<sha-or-ref>"
}

Field requirements:

• kind: "local" requires an absolute path.
• kind: "catalog" requires a catalog name for new writes.
• kind: "builtin" has no additional required fields.
• kind: "git" is schema-only and forward-compatible. No git producer is included in this change; future producers must provide a URL and may provide a ref.

2. Thread an optional source value through install_from_directory in both managers and through the command-level catalog installation callers.

3. Record the true source at call sites:

• Bundled installations use {"kind": "builtin"}.
• User-supplied local paths use {"kind": "local", "path": "<resolved-source-path>"}.
• Catalog installations use {"kind": "catalog", "catalog": "<catalog-name>"}.

The default local path must be the resolved original source_dir, not the installation destination under .specify.

4. Add shared validation and normalization helpers:

• _validate_source(raw) validates values before they are written.
• _normalize_source(raw) normalizes legacy values when returned from registry read APIs.
• Registry writes store a defensive deep copy of the validated value.

5. Normalize legacy values on read without rewriting registry files:

missing / None → {"kind": "local"}
"local"         → {"kind": "local"}
"catalog"       → {"kind": "catalog", "catalog": null}
structured dict → validate and return

{"kind": "catalog", "catalog": null} is a legacy-only read sentinel. New writes must reject it.

6. Preserve provenance through force reinstalls, rollback, backup restoration, registry updates, and failed-install cleanup.

Alternatives Considered

• Add separate install_from_catalog or install_from_git methods. Rejected because catalog installations already flow through install_from_directory, and no git-install pathway exists.
• Infer provenance from the installed filesystem. Rejected because extraction removes the original source context and filesystem shape cannot reliably distinguish local and catalog installations.
• Keep legacy strings indefinitely. Rejected because consumers would need to handle multiple incompatible representations.
• Duplicate source validation and normalization in each registry. Rejected because the implementations could diverge.

Component

Specify CLI — initialization, commands, installation, and registry metadata.

AI Agent (if applicable)

Not applicable.

Use Cases

1. A wizard can distinguish a preset installed from a named catalog from one installed from a local directory.
2. Future preset list --json and extension list --json commands can expose truthful installation origin.
3. Support and reproducibility tooling can identify how an installed package entered the project.
4. Future git installation can use the schema without another registry migration.

Acceptance Criteria

• ExtensionManager.install_from_directory and PresetManager.install_from_directory accept an optional structured source value.
• Source values are validated before persistence and stored as defensive deep copies.
• When no source is supplied, the default is {"kind": "local", "path": str(source_dir.resolve())}.
• The default path refers to the original source directory, not the installation destination.
• Paths are stored as absolute paths.
• The hard-coded "source": "local" literal is removed from both install methods.
• Bundled, local, and catalog call sites pass the correct source kind.
• Catalog provenance is supplied by the command-level install caller that resolves the catalog entry and invokes install_from_directory; download helpers do not determine provenance.
• A shared internal module defines SourceInfo, _validate_source, and _normalize_source.
• Both registries import and use the shared definitions.
• get() and list() read methods return normalized structured source values without rewriting existing registry files.
• Missing, "local", and legacy "catalog" values normalize as specified.
• New writes reject unknown kinds, invalid types, missing required fields, unknown fields if the schema policy disallows them, and direct use of the legacy catalog: null sentinel.
• git is accepted as a schema-only kind, with no git-install producer required.
• Force reinstall, backup, rollback, restore, registry update, and failed-install paths preserve or remove provenance consistently.
• The registry schema-version decision is documented explicitly in the pull request description and changelog.
• Existing tests and fixtures containing "source": "local" are audited and classified as either current-install fixtures or intentional legacy-normalization fixtures.
• Tests cover local, catalog, and builtin round trips; default source-path behavior; legacy normalization; defensive-copy behavior; invalid source values; catalog installation through the command-level path; force reinstall and rollback behavior; and registry restore and update behavior.
• Extension and preset API documentation describes the structured source schema, absolute-path behavior, legacy normalization, read-only normalization policy, and schema-only git support.

Additional Context

Blocks preset list --json and extension list --json, which are tracked separately.

[github-actions]

Feature assessment — structured-provenance-registry · Stage 1/5: Intake

Idea Intake: Record Structured Provenance for Installed Presets and Extensions

• Slug: structured-provenance-registry
• Created: 2026-08-19
• Source: GitHub issue [Feature]: Record structured provenance for installed presets and extensions #4208 (pasted text; github.com — allowlisted)
• Type: improvement

Idea (as captured)

ExtensionRegistry and PresetRegistry currently record a hard-coded "source": "local" value for every installation, including packages installed from downloaded catalog archives. This loses the distinction between local-directory, catalog, and bundled installations.

Proposed solution defines a shared internal SourceInfo schema ({kind, catalog, path, url, ref}), threads an optional source value through install_from_directory in both managers and catalog callers, validates/normalizes on write/read, and normalizes legacy values on read without rewriting files.

Restated

Both ExtensionManager and PresetManager currently hard-code "source": "local" in registry metadata regardless of how a package was actually installed (locally, from a catalog, or as a bundled built-in), making installation origin indistinguishable. This improvement replaces the flat string with a validated, structured SourceInfo schema and normalizes legacy values on read.

Origin & Context

• Raised by: nicolehaugen
• Trigger: Blocking dependency for preset list --json and extension list --json commands (tracked separately); registry schema also needs forward-compatibility for a future git-install pathway.

First-Glance Unknowns

• [NEEDS CLARIFICATION: Should the SourceInfo schema be versioned separately, or is it implicitly versioned by the registry schema version?]
• [NEEDS CLARIFICATION: What is the current registry schema version, and will this change bump it?]
• [NEEDS CLARIFICATION: Are there any external consumers (plugins, scripts) that currently read the raw "source": "local" string and would break on the structured schema?]
• [NEEDS CLARIFICATION: Should the path in a local source be stored as an absolute POSIX path or platform-native?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4208 · 541.9 AIC · ⌖ 13.1 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — structured-provenance-registry · Stage 2/5: Research

Idea Research: Record Structured Provenance for Installed Presets and Extensions

• Slug: structured-provenance-registry
• Created: 2026-08-19
• Evidence confidence (overall): high

Users & Demand

• Blocked downstream feature: preset list --json and extension list --json require truthful installation origin — the issue explicitly identifies this blocker. — [source: issue [Feature]: Record structured provenance for installed presets and extensions #4208] (confidence: high, cited)
• Support and reproducibility tooling needs provenance to identify how a package entered a project. — [source: issue [Feature]: Record structured provenance for installed presets and extensions #4208] (confidence: medium, cited)
• Future git-install pathway requires the schema to be forward-compatible now to avoid another registry migration later. — [source: issue [Feature]: Record structured provenance for installed presets and extensions #4208] (confidence: medium, cited)

Prior Art

• Workflows registry already writes partial structured source (src/specify_cli/workflows/_commands.py lines 1086, 2488, 3492): workflow and step catalog installs write "source": "catalog" plus "catalog_name" and "url" as sibling fields — a flat string plus peers, not a nested struct. Closest precedent in the codebase; the pattern is already partially ad-hoc. — [source: codebase, direct inspection] (confidence: high, cited)
• Extension and preset registries hard-code "source": "local" regardless of install path (extensions/__init__.py:2619, presets/__init__.py:3583). Catalog-installed packages thus appear identical to locally-sourced ones. — [source: codebase] (confidence: high, cited)
• Both registries carry SCHEMA_VERSION = "1.0" (extensions/__init__.py:741) but no registry-file-level version check is applied to the source field specifically. — [source: codebase] (confidence: high, cited)
• Tests use flat "source": "local" and "source": "catalog" strings in fixture data (71 occurrences across test_extensions.py, test_presets.py, test_workflows.py). These need audit/reclassification on implementation. — [source: codebase grep] (confidence: high, cited)
• Industry analogues: npm's package-lock.json uses resolved/integrity/bundled per entry; pip's direct_url.json (PEP 610) uses a structured, install-type-keyed dict. The proposed SourceInfo mirrors this pattern well-established in package managers. — [source: ASSUMPTION, industry knowledge] (confidence: high, assumption)

Market & Context

• Users currently cannot programmatically distinguish a preset installed from a catalog from one installed from a local path; workarounds require inspecting filesystem paths or relying on ad-hoc sibling fields. — [source: issue [Feature]: Record structured provenance for installed presets and extensions #4208 + codebase] (confidence: high, cited)
• Cost of doing nothing: --json list commands remain blocked; future git-install would force another schema migration; catalog reinstall/update guards in workflows/_commands.py:1051, 2456 continue relying on brittle flat-string comparison. — [source: codebase] (confidence: high, cited)

Data & Constraints

• 71 test fixture occurrences of flat "source" strings across 4 test files — internal-only, controlled one-time update. — [source: codebase grep] (confidence: high, cited)
• Registry files at .specify/extensions/.registry and .specify/presets/.registry — existing projects will have flat-string "source" values that must be normalized on read without file rewrites. — [source: codebase + issue [Feature]: Record structured provenance for installed presets and extensions #4208] (confidence: high, cited)
• git kind is schema-only, no producer required; schema must accept the kind without an install pathway. — [source: issue [Feature]: Record structured provenance for installed presets and extensions #4208] (confidence: high, cited)

Evidence Against the Idea

• Scope risk: 24 acceptance criteria touching install_from_directory, two registry classes, catalog callers in workflows/_commands.py, normalization helpers, and a new shared module — medium change with extensive cross-cutting test fixture updates.
• Workflows registry inconsistency: Workflows already write a quasi-structured record (source + catalog_name + url as siblings) that does not conform to the proposed nested SourceInfo. The issue does not scope workflows alignment, which could leave three registries with three different formats.
• Schema version decision deferred: The issue defers the version-bump decision to the PR, creating risk of inconsistent policy between registries if not handled carefully.

Gaps & Open Questions

• [NEEDS CLARIFICATION: Will the workflows registry also migrate to SourceInfo, or remain with its current ad-hoc shape?]
• [NEEDS CLARIFICATION: Should SCHEMA_VERSION be bumped, and what is the migration path for existing .registry files?]
• [NEEDS CLARIFICATION: Will path be stored as POSIX string or platform-native for cross-platform portability?]

Sources

• GitHub issue [Feature]: Record structured provenance for installed presets and extensions #4208 (host: github.com, policy: allowlisted)
• src/specify_cli/extensions/__init__.py, src/specify_cli/presets/__init__.py, src/specify_cli/workflows/_commands.py (local codebase)
• tests/test_extensions.py, tests/test_presets.py, tests/test_workflows.py (local codebase)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4208 · 541.9 AIC · ⌖ 13.1 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — structured-provenance-registry · Stage 3/5: Problem

Problem Definition: Record Structured Provenance for Installed Presets and Extensions

• Slug: structured-provenance-registry
• Created: 2026-08-19
• Inputs used: intake.md | research.md

Problem Statement

Both ExtensionManager and PresetManager hard-code "source": "local" in registry metadata for every installation, making it impossible to distinguish packages installed from local directories, named catalogs, or as bundled built-ins — and blocking --json list commands that need to report truthful origin.

Affected Users & Stakeholders

• Users: Spec Kit project maintainers and automation authors — they cannot programmatically determine how an installed preset or extension entered their project, making reproducibility, audit, and support harder.
• Stakeholders: Spec Kit CLI team — the missing provenance blocks preset list --json and extension list --json features; also affects catalog update guards that currently rely on a brittle flat-string "source" comparison.

Goals

• Registry entries for extensions and presets record the true installation kind (local, catalog, builtin, or schema-only git).
• Catalog installs record the catalog name; local installs record the resolved absolute source path; builtin installs carry no extra required fields.
• Legacy flat-string values in existing registry files are normalized to the structured form on read, without rewriting files.
• A shared validation/normalization module prevents the two registries from diverging on the schema.
• The schema is forward-compatible for a future git-install pathway.

Non-Goals

• Migrating the workflows registry to SourceInfo (out of scope per the issue).
• Implementing a git-install pathway (schema-only).
• Exposing origin in any CLI output command (that is the blocked downstream feature).
• Altering registry file format on disk (read-time normalization only; no file migration).

Success Metrics

• "source": "local" no longer appears as a literal in install_from_directory bodies (baseline: 2; target: 0).
• All call sites pass a correct structured source — verified by code review and tests.
• Existing registry files with flat-string "source" values return normalized structured values without being rewritten — verified by round-trip tests.
• Test coverage: local/catalog/builtin round-trips; default-path behavior; legacy normalization; defensive-copy; invalid-value rejection; catalog command-level path; force reinstall/rollback; registry restore/update.

Cost of Inaction

preset list --json and extension list --json remain blocked. Catalog update guards continue relying on brittle flat-string comparisons. A future git-install pathway would require a second schema migration. Users and tooling cannot determine how installed packages entered a project.

Open Questions

• [NEEDS CLARIFICATION: Will the workflows registry be aligned to SourceInfo in a follow-on?]
• [NEEDS CLARIFICATION: Is a SCHEMA_VERSION bump required, and what is the migration path for existing .registry files?]
• [NEEDS CLARIFICATION: Should path in local kind be POSIX-normalized for cross-platform portability?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4208 · 541.9 AIC · ⌖ 13.1 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — structured-provenance-registry · Stage 4/5: Concept

Concept: Record Structured Provenance for Installed Presets and Extensions

• Slug: structured-provenance-registry
• Created: 2026-08-19
• Recommended option: Option A — Shared SourceInfo module with read-time normalization

Options

Option A — Shared SourceInfo module with read-time normalization

• Sketch: Add a new shared internal module (e.g., src/specify_cli/_source_info.py) that defines the SourceInfo schema, _validate_source(raw), and _normalize_source(raw). Both ExtensionManager.install_from_directory and PresetManager.install_from_directory gain an optional source parameter defaulting to {"kind": "local", "path": str(source_dir.resolve())}. Catalog callers at command level pass the appropriate structured value. Registry get() and list() normalize on read. Legacy flat strings ("local", "catalog", missing/None) normalize silently without file rewrites; new writes validate and reject invalid kinds, missing required fields, and the legacy catalog: null sentinel.
• Appetite: medium (weeks)
• Trade-offs: Clean separation; single schema source of truth; both registries stay consistent; backward-compatible for existing project files. Requires threading source through method signatures and catalog callers.
• Rabbit holes: 24 acceptance criteria cover force-reinstall, rollback, restore, and registry-update provenance paths — each needs explicit testing. The workflows registry uses a related-but-different shape; the implementer must decide early whether to align it in scope or leave it.

Option B — Per-registry source handling (no shared module)

• Sketch: Each registry handles its own source validation/normalization independently.
• Appetite: small-medium
• Trade-offs: Smaller initial surface. Rejected in the issue: implementations could diverge and the shared-module work would be deferred to a cleanup that may never happen.
• Rabbit holes: Schema drift between registries; deferred maintenance debt.

Option C — Do nothing / defer until --json commands

• Sketch: Leave "source": "local" in place; normalize on-the-fly in list commands only.
• Appetite: small (deferred)
• Trade-offs: Unblocks nothing now; defers the fix to a moment of time pressure. Catalog update guards remain brittle.
• Rabbit holes: Problem compounds as more install paths land.

Recommendation

Option A — Shared SourceInfo module with read-time normalization.

The problem is well-defined, scope is bounded, and the shared-module approach directly addresses all stated acceptance criteria. The issue explicitly rejects Options B and C. Option A aligns with the detailed requirements, unblocks downstream --json commands, and makes the schema forward-compatible for git-install without additional changes.

Out of Scope (for the recommended option)

• Workflows registry migration to SourceInfo.
• Any CLI-visible output changes.
• Git-install producer (schema-only git kind acceptance).
• Registry file-format migration on disk.

Assumptions to Validate

• Shared module can be imported by both registries without circular imports.
• Catalog callers in workflows/_commands.py are the correct provenance-passing site for extensions/presets (not inside install_from_directory itself).
• Read-time normalization is sufficient — no code path writes get() results back to the registry in a way that would accidentally rewrite legacy strings.
• Schema-version bump decision can be deferred to the implementer without blocking the feature.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4208 · 541.9 AIC · ⌖ 13.1 AIC · ⊞ 38.1K · ◷

[github-actions]

Feature assessment — structured-provenance-registry · Stage 5/5: Decision — verdict go

Decision: Record Structured Provenance for Installed Presets and Extensions

• Slug: structured-provenance-registry
• Decided: 2026-08-19
• Verdict: go
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	Hard-coded "source": "local" demonstrably loses installation origin; confirmed by codebase inspection. Real impact on downstream features and update guards.
Evidence strength	adequate	Problem and solution grounded in codebase evidence; industry analogues (PEP 610, npm lock) support the schema pattern. Minor assumptions on cross-platform path format and circular-import risk are marked.
Value vs. inaction	strong	Directly unblocks preset list --json / extension list --json; removes brittle flat-string guards; prevents a second schema migration for git-install.
Feasibility / appetite	adequate	Medium appetite (weeks). Option A is credible and well-specified. Main uncertainty is the workflows-registry alignment question.
Strategic fit	strong	Aligns with Specify CLI's goal of reliable, auditable project state. Internal debt item recognized by the maintainer.
Risk posture	adequate	Key risks identified: 71 test fixture occurrences to update, circular-import check, workflows registry inconsistency, schema-version decision. None are unmitigated blockers; all have clear resolution paths.

Verdict & Rationale

go. The problem is real and confirmed by code. Evidence strength is adequate — all key claims are citable from the codebase, and open questions are implementation details rather than concept-invalidating unknowns. The recommended option (shared SourceInfo module with read-time normalization) is bounded, well-specified by 24 acceptance criteria, and directly unblocks a tracked downstream feature.

Handoff to /speckit.specify

• Problem: Both ExtensionManager and PresetManager hard-code "source": "local" in registry metadata regardless of actual install origin, making provenance indistinguishable and blocking --json list commands.
• Chosen approach: Option A — Add src/specify_cli/_source_info.py with SourceInfo schema, _validate_source, and _normalize_source; thread optional source param through install_from_directory in both managers; pass correct structured source at catalog callers; normalize legacy values on read without rewriting files.
• In scope: Extension and preset registries; install_from_directory signatures; catalog callers in workflows/_commands.py; shared validation/normalization module; legacy normalization; test fixture audit.
• Out of scope: Workflows registry migration; CLI output commands; git-install producer; registry file migration on disk.
• Success metrics: Zero "source": "local" literals in install_from_directory bodies; all call sites pass structured source; legacy flat strings normalize correctly on read; full test coverage per acceptance criteria.
• Carried-forward open questions:
  • Will the workflows registry align to SourceInfo in a follow-on?
  • Is a SCHEMA_VERSION bump required, and what is the compatibility path?
  • Should path in local kind be POSIX-normalized for cross-platform portability?

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4208 · 541.9 AIC · ⌖ 13.1 AIC · ⊞ 38.1K · ◷